NAME

sticker - sticks tags onto files, populates a database with file meta-data

VERSION

version 3.0101

SYNOPSIS

sticker --help | --manpage | --version | --settings { schema | all | I<name> }

sticker [--verbose] [ --readonly ] [--disable I<module> ] I<other options>

sticker [--derive] --add I<string>=I<string> file [file ...]
sticker --delete I<string> file [file ...]
sticker --extract file [file ...]
sticker --from_file I<otherfile> file [file ...]

sticker --missing
sticker --overlooked file ...
sticker --removed file ...
sticker --update file ...

sticker --query query-string ...
sticker --file_info file ...
sticker --db_info file ...
sticker --has_data file
sticker --tags

DESCRIPTION

This writes meta-data into files, reads meta-data from files, and populates a database with that information. It also deletes from and queries the database.

OPTIONS

--add string=string

Set the given field in the given file(s).

--db_info

Show the information about the given file(s) from the database.

--delete string

Delete the given field from the given file(s).

--derive

Derive the needed value of the given field from other information in the given file. At the moment, this only works for deriving a "title" field from the filename.

--disable module

Disable the given module for reading and writing. By default, all installed modules are enabled.

--extract

Extract metadata in other formats (e.g. EXIF data) from the file and save as extended attributes to the same file.

--from_file filename

Extract metadata from this file and use it to set the metadata in the other file(s).

--help

Display short help and exit.

--file_info

Show the metadata information of the given file(s), from the files. This option is useful for when the file is not (yet) in the database, or has not yet been updated after a change.

--manpage

Display full documentation and exit.

--missing

Display files which are in the database but missing from the filesystem.

--overlooked

From the given files, show which ones have been overlooked (are not in the database).

--query string

Query the database for the list of files matching the given tag(s).

--quiet

Make the output quiet (no output).

--readonly

Disable database update, only enable queries.

--removed

Tell the database that the given file(s) are to be removed from the database. (Can't use "delete" because that is used for deleting fields from files). This is used for either removing files that no longer exist (see "missing") or files which have been mistakenly added that you didn't mean to add. It is the latter situation which is why "missing" and "removed" are separate options.

If you want to remove missing files in one line, use the following command:

sticker --removed $(sticker --missing)

--settings type

schema

Display the database schema and exit.

all

Display all the current settings and exit.

name

Display the value for the given setting and exit.

--tags

Display the values of all the tags in the database and exit.

--update

Update the database with the metadata from the given file(s).

--verbose

Make the output verbose.

--version

Display the current version and exit.

DATA DEFINITION

The data which is considered significant needs to be defined before it can be used for fields in the database or for meta-data in the files. Some fields are derived from file information from every file (they are read-only). Some fields are common for certain file types (such as song-titles in MP3 files), but are still read-write rather than just read only. Other fields are completely new, and need to be defined more fully.

In addition, there are other data-definition options which are purely related to the structure of the database and how queries are handled.

primary_table name

Name of the primary table in the database. This contains all the raw data, but there are other tables which will be derived from this, for convenience and ease of use.

topdir directory

If the files you are using are all in the same directory tree, this option is for designating what is the top directory in that tree. This is used for deriving a number of values related to the file name.

wanted_fields name=type

Defines the non-derived fields you want. This includes filetype-specific fields which are standard for that filetype; you still need to define these.

The name is the name of the field. If the name matches a standard field for that filetype (such as "song" for MP3 files) then that specific meta-data is used. Otherwise a new field is created for that file.

The type is the type of the field. This can be one of the following:

TEXT

Just ordinary text.

MULTI

A multi-valued field. Used for things like tags, where you want to have multiple values that can be queried separately.

NUMBER

A number. Generally only important if you want to access the database with your favourite SQLite database tool and do something that you can only do with numbers, such as add them up, or order them numerically.

read_all

Read all possible meta-data, rather than just that in the wanted fields, including that which can be derived.

field_order name

Defines the order of the fields in the primary database table. This is where you say which derived fields you want, as well as the non-derived fields you want.

taggable_fields name=prefix

Define which fields you want to be used as "tags". These may or may not be multi-value fields. If this option is used, then a new table (a view) will be created called primary_table_info which will be used for queries instead of the primary table. It will contain a new field called "faceted_tags" which will contain a combination of all the taggable fields you define here. If prefix is given, then the values from that field will be given that prefix when they are put into the "faceted_tags" field. If prefix is empty, then either no prefix will be given, or, if tagprefix is true, the prefix will be the field name.

tagfield name

If you are not using multiple taggable fields, say which field you are designating as the "tag" field. This is the field which will be used for queries (see --query). If this option is not used, the default value is "tags".

tagprefix

If this is true, then the values of tag fields will be given a prefix which is "fieldname-", the name of that tag field.

Derived Fields

The following fields are read-only fields derived from the common file information:

file

The full name of the file.

basename

The base-name of the file including the extension.

id_name

The base-name of the file excluding the extension.

ext

The extension part of the file name.

relpath

The path of the file relative to the topdir value. If no topdir is given, this field is not derived.

thumbnail

The relative path of a thumbnail file. A thumbnail file is a .jpg or .png file which is in a ".thumbnails" directory below the given file, and has a base-name-without-extension which matches the given file.

If no topdir is given, this field is not derived.

grouping

The first three parts of the relative path of the directory file is in; useful for grouping together files which are in subdirectories. If no topdir is given, this field is not derived.

sectionN

The Nth section of the relative path of the directory the file is in. Useful if you have put the files into subdirectories with meaningful names. If no topdir is given, this field is not derived.

filesize

The size of the file.

filedate

The modification time of the file.