README.md 5.7 KB
Newer Older
Sam Thursfield's avatar
Sam Thursfield committed
1 2 3
TAGCLOUD
========

Sam Thursfield's avatar
Sam Thursfield committed
4 5
Tagcloud is a GTK+ application that lets you explore all the junk on your
computer, and you can apply text labels to things to try and organise it.
Sam Thursfield's avatar
Sam Thursfield committed
6

Sam Thursfield's avatar
Sam Thursfield committed
7 8 9 10 11
It is at an early stage of development.

Here is a screenshot!

![](docs/screenshot-20170929.png)
Sam Thursfield's avatar
Sam Thursfield committed
12 13 14 15 16 17

Developer information
---------------------

Tagcloud requires GTK+ 3, Python 3, PyGObject and Tracker.

18 19 20
There is a BuildStream project provided which allows you to produce a Flatpak
application bundle of Tagcloud. The following commands should work assuming you
have BuildStream, the bst-external plugins repo and Flatpak available:
Sam Thursfield's avatar
Sam Thursfield committed
21

Sam Thursfield's avatar
Sam Thursfield committed
22
    cd flatpak
23 24
    bst build tagcloud-flatpak.bst
    ./deploy.sh
Sam Thursfield's avatar
Sam Thursfield committed
25

Sam Thursfield's avatar
Sam Thursfield committed
26 27 28 29
You can then run it with this command:

    flatpak run uk.me.afuera.Tagcloud

30 31 32
Tagcloud has an automated test suite which can be run via `meson test`.
The most reliable way to run this is inside the application bundle environment
using `bst shell`.
33

34 35
First you must build the test environment, and create a build tree with the
correct configuration, as in the following example:
36

37 38 39
    bst build tagcloud-test-environment.bst
    bst shell tagcloud-test-environment.bst --mount ~/tagcloud /src \
        -- sh -c 'cd /src; mkdir build; meson ./build --prefix=/app'
40

41
Once this is done, you can run the test suite as follows.
42

43 44
    bst shell tagcloud-test-environment.bst --mount ~/tagcloud /src \
        -- sh -c 'cd /src/build; xvfb-run dbus-launch meson test --print-errorlogs'
45

46 47 48 49
You can also use the test environment to run the Tagcloud application. This is
NOT the same as running it under Flatpak and is not a substitute for real
testing, but it can be much quicker when debugging as you can execute code
directly from the source tree. The following example works for me:
50

51 52
    bst shell tagcloud-test-environment.bst --mount ~/tagcloud /src \
        --mount /etc /etc --mount /home /home --mount /run /run \
53
        -- sh -c "cd /src/build; env HOME=$HOME ninja run-uninstalled"
54

55 56
You can also use this method to run an interactive `bash` session, and to run
the application under the `gdb` debugger.
57

58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89
Tracker domains
---------------

The Tracker indexer and database used by Tagcloud can be operated in several
ways. Originally the design was for a single session-wide set of Tracker
services that had knowledge of all the user's files. This is the most efficient
approach and allows for searches across all data stored by all applications.

However, this approach prevents any kind of fine-grained sandboxing of
applications -- users either give an app access to all their data, or none. It
also means that all apps have to use whatever version of Tracker is provided
by the user's distribution which makes it hard to use any new features. The
2.0 release of Tracker added a new
[domains](https://developer.gnome.org/libtracker-sparql/unstable/tracker-private-store.html)
feature which makes it practical for an app to have its own private instance
of the Tracker services.

Tagcloud uses the session-wide Tracker store by default but it also supports
using a private Tracker instance. This can be enabled by passing
`--tracker-domain app` on the commandline when starting Tagcloud.

If you followed the instructions above for installing Tagcloud into a custom
prefix like `/opt/tagcloud`, you will need to modify your D-Bus session bus
config so that the D-Bus .service files for the private Tracker instance can be
found. To achieve this I created a file named
`/etc/dbus-1/session.d/tagcloud.conf` with the following contents:

    <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-Bus Bus Configuration 1.0//EN"
        "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
    <busconfig>
      <servicedir>/opt/tagcloud/share/dbus-1/services/</servicedir>
    </busconfig>
Sam Thursfield's avatar
Sam Thursfield committed
90 91 92 93

Plan
----

Sam Thursfield's avatar
Sam Thursfield committed
94 95 96
Here is a professionally-drafted UI mockup:

![](docs/design-1.0.jpg)
Sam Thursfield's avatar
Sam Thursfield committed
97

Sam Thursfield's avatar
Sam Thursfield committed
98 99 100
Here is an incomplete TODO list:

### 1.0
Sam Thursfield's avatar
Sam Thursfield committed
101

Sam Thursfield's avatar
Sam Thursfield committed
102
Filter content by containing folder, type.
Sam Thursfield's avatar
Sam Thursfield committed
103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121

Filter by text search

Open content in the relevant application from the content list's context menu

Page through long sets of content (allow viewing more than the first 100 results).

"Pretty" view of content list:

  * icon for type
  * filename hidden if title available
  * artist, title and album info shown for music
  * thumbnail / media art shown if possible
  * tags shown for each item

Sort content by Name, First Modified, Last Modified, Size, or Type.

Sort tags by Label, or Size.

Sam Thursfield's avatar
Sam Thursfield committed
122 123 124
Use a programmatic SPARQL query generator instead of blindly joining
strings together. (https://github.com/pudo/sparqlquery may be the best bet).

Sam Thursfield's avatar
Sam Thursfield committed
125 126
Provide a Flatpak

Sam Thursfield's avatar
Sam Thursfield committed
127 128 129 130 131 132 133 134 135 136 137
### 1.2

Store and edit notes about files.

Handle removable devices and folders outside the usual Tracker index (the
IndexFileForProcess call should be useful here).

Show tag filter as a path bar in the headerbar.

gnome-shell search provider for tags

Sam Thursfield's avatar
Sam Thursfield committed
138 139 140
Read and write tags as xattrs in the file system (using tracker-miner-fs and
tracker-writeback). Ideally be compatible with KDE's Baloo framework.

Sam Thursfield's avatar
Sam Thursfield committed
141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157
### 2.0

Support for remote sources:

  * last.fm -- import music tags
  * pinboard.in -- import document tags and notes

Importing from these should be done with a simple Tracker miner. This should be
done into a separate Tracker store, at least initially.

Credential storage should be done with gnome-online-accounts but we may need to
hack it in locally initially.

Tags from remote services should be visually distinct.

Writing tags and notes back to the remote services can be done too.

Sam Thursfield's avatar
Sam Thursfield committed
158 159
Suggestions for which tags to add based on existing information.

Sam Thursfield's avatar
Sam Thursfield committed
160 161 162 163 164 165
### Undecided

Show music content hierarchically, with artists or albums expanding to the
actual tracks. Expose this feature with a button next to Music in the Content
Type menu.

Sam Thursfield's avatar
Sam Thursfield committed
166 167 168 169
Heirarchical tags

Links to online databases for info on a given resource (e.g. Musicbrainz
for music)