quodlibet-3.9.1/ 0000755 0001750 0001750 00000000000 13115513301 013733 5 ustar lazka lazka 0000000 0000000 quodlibet-3.9.1/docs/ 0000755 0001750 0001750 00000000000 13115513301 014663 5 ustar lazka lazka 0000000 0000000 quodlibet-3.9.1/docs/icons.rst 0000644 0001750 0001750 00000001247 13112005742 016536 0 ustar lazka lazka 0000000 0000000 .. |ubuntu-logo| raw:: html
.. |debian-logo| raw:: html
.. |fedora-logo| raw:: html
.. |opensuse-logo| raw:: html
.. |windows-logo| raw:: html
.. |source-logo| raw:: html
.. |arch-logo| raw:: html
.. |macosx-logo| raw:: html
.. |github-logo| raw:: html
.. |bug-logo| raw:: html
.. |linux-logo| raw:: html
quodlibet-3.9.1/docs/features.rst 0000644 0001750 0001750 00000005512 13112005742 017240 0 ustar lazka lazka 0000000 0000000 .. _Features:
Features
========
Audio Playback
^^^^^^^^^^^^^^
* Multiple audio back-ends (GStreamer, xine-lib)
* Replay Gain support
* Auto-selects between 'track' and 'album' mode based on
current view and play order
* Applies clipping prevention whenever available
* Configurable default (fallback) and pre-amp values to suit any audio setup
* Multimedia key support
* Real shuffle mode, that plays the whole playlist before repeating
* Weighted (by rating) random playback
* Proper 'Previous' support in shuffle mode
* A play queue
* Bookmarks within files (or playlists, with a plugin)
Editing Tags
^^^^^^^^^^^^
* Full Unicode support
* Make changes to many files at once
* Make changes across all supported file formats
* Tag files based on their filenames with configurable formats
* Rename files based on their tags
* No ugly ``%a``, ``%t`` patterns -
more readable ````, ```` instead
* Fast track renumbering
* See full instructions at :ref:`EditingTags`
Audio Library
^^^^^^^^^^^^^
* Watch directories and automatically add/remove new music
* Hide songs on removable devices that may not always be there
* Save song ratings and play counts
* Lyrics downloading and saving
* Internet Radio ("Shoutcast") support
* Audio Feeds ("Podcast") support
User Interface
^^^^^^^^^^^^^^
* Simple user interface to Just Play Music if you want
* Useful as a small window or maximized, no feeling cramped or wasted space
* Album cover display
* Full player control from a tray icon
* Recognize and display many uncommon tags, as well as any others you want.
Especially useful for classical music.
Library Browsing
^^^^^^^^^^^^^^^^
* Simple or regular-expression based search
* Constructed playlists
* iTunes/Rhythmbox-like paned browser, but with any tags you want
(Genre, Date, etc)
* Album list with cover art
* By directory, including songs not in your library
Python-based plugins
^^^^^^^^^^^^^^^^^^^^
* Automatic tagging via `MusicBrainz `_ and CDDB
* On-screen display popups
* Last.fm/AudioScrobbler submission
* Tag character encoding conversion
* Intelligent title-casing of tags
* Find (and examine / remove) near-duplicate songs across your
entire collection
* Audio fingerprinting of music
* Control Logitech Squeezebox devices.
* Scan and save Replay Gain values across multiple albums at once
(using gstreamer)
File Format Support
^^^^^^^^^^^^^^^^^^^
* MP3, Ogg Vorbis / Speex / Opus, FLAC, Musepack, MOD/XM/IT, Wavpack,
MPEG-4 AAC, WMA, MIDI, Monkey's Audio
UNIX-like integration
^^^^^^^^^^^^^^^^^^^^^
* Player control, status information, and querying of library
from the command line
* Can used named pipes to control running instance.
* Now-playing is available as a fixed file
quodlibet-3.9.1/docs/translation/ 0000755 0001750 0001750 00000000000 13115513301 017221 5 ustar lazka lazka 0000000 0000000 quodlibet-3.9.1/docs/translation/index.rst 0000644 0001750 0001750 00000000126 13112005742 021063 0 ustar lazka lazka 0000000 0000000 Translation Guide
=================
.. toctree::
:titlesonly:
howto
faq
quodlibet-3.9.1/docs/translation/howto.rst 0000644 0001750 0001750 00000005226 13115500547 021130 0 ustar lazka lazka 0000000 0000000 .. _Translating:
How-to
======
If you're fluent in a language other than English, and have some spare
time, you can help us translate Quod Libet. Translation is a continuous
process on an active projects like this - as developers add new features or
modify existing text used, new translations will be needed. Many of the
translations files are missing a lot of strings, so please try the trunk
version in your language.
Of course, there might be mistakes in the English, too! Please let us know
if you find them.
Translation Software
--------------------
To translate, you'll want to have intltool, gettext and git installed::
apt-get install intltool gettext git
For translating itself you need a PO editor like `Poedit
`_::
apt-get install poedit
Translation Process
-------------------
Get the QL code::
$ git clone https://github.com/quodlibet/quodlibet.git quodlibet
$ cd quodlibet/quodlibet
To translate the last release, update to the stable branch::
$ git branch -a # to get the list of branches
$ git checkout quodlibet-X.X # for example: quodlibet-3.3
To translate current trunk, update to the default branch::
$ git checkout master
You can find the translation file for your chosen language in::
./po/.po
In case there's not already a translation for your language, create one::
$ ./setup.py create_po --lang=
Create the POT file and update translations so all new strings that were added
since the last translation update get included::
$ ./setup.py update_po --lang=
Now start translating...
::
$ poedit ./po/.po
Test the translation by generating MO files and running Quod Libet and Ex
Falso. build_mo will create a 'build' directory including the processed
translations and if 'build' is present QL/EF will use these translations
instead of the global ones.
::
$ ./setup.py build_mo
$ ./quodlibet.py
$ ./exfalso.py
If your active system language is not the one you are translating, you can
run them like::
$ LANG= ./quodlibet.py
Finally run our unit tests to make sure the translation will not cause
programming errors. If it says something else, there's a problem with the
translation.
::
$ ./setup.py build_mo
$ ./setup.py test --to-run PO.
And send us the .po file you made:
* Create a `new issue
`__ linking to your
updated .po file. If you don't have a place for making the file accessible
create a `gist `__ with the content of the .po
file and include the gist URL in the issue description.
* Or create a pull request.
quodlibet-3.9.1/docs/translation/faq.rst 0000644 0001750 0001750 00000010564 13112005742 020532 0 ustar lazka lazka 0000000 0000000 FAQ
===
What do these things in strings mean?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* ``This is %s``, ``an %(foobat)s example``, ``for {translators}, {0}``:
see `String Formatting`_
What does ``msgctxt`` in the .po files mean?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It stands for message context and (optionally) allows for different
translations of the same translatable text appearing in different contexts.
For example the word "Search" could be a title of a window or the label of a
button. The former meaning "a search" and the latter "to search".
Why are some strings not translatable?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In case of strings like "Apply" and "Ok" that show up on buttons, these
come from GTK and are not part of QL. But there is a chance that we have
forgotten to mark a string translatable, so please contact us.
If anything else is not translatable you can start QL with the following
variable set::
QUODLIBET_TEST_TRANS=xx ./quodlibet.py
which will append and prepend "xx" to all translatable strings.
What does `titlecase?` mean?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There's a special string `titlecase?` which should be translated as
anything if your language does not use `title casing
`_ (eg *This Is Title Casing*)
for labels. If it is left untranslated, title-casing will be used.
String Formatting
^^^^^^^^^^^^^^^^^
Some strings include replacement tokens like ``%s`` or ``{foobar}``. These
mark places where text gets replaces at runtime, so they should be carried
over to the translation without changing their content.
Some examples showing the strings to translate and the resulting strings
where the tokens have been replaced:
* ``Hello %s`` -> ``Hello Lou``
* ``The number %d`` -> ``The number 42``
* ``Hello %(name)s`` -> ``Hello Lou``
* ``Hello {name}`` -> ``Hello Lou``
* ``Hello {0}`` -> ``Hello Lou``
* ``Hello {0.name}`` -> ``Hello Lou``
* ``Hello {}`` -> ``Hello Lou``
In the case of ``Hello %(name)s``, a possible German translation and text
displayed to the user would be ``Hallo %(name)s`` and ``Hallo Lou``.
Plural-Forms
^^^^^^^^^^^^
The first thing you need is a Plural-Forms line for your language. The GNU
gettext manual has a chapter on plural forms with examples for many
languages. This should go after the "Content-Transfer-Encoding" line.
The Plural-Forms line tells gettext how many plural forms there are in the
language and how to use them. For example:
::
msgid "artist"
msgid_plural "artists"
msgstr[0] "artist"
msgstr[1] "artists"
The English plural expression, "n != 1" means to use msgstr[0] if the count
is 1, otherwise use msgstr[1]. If your language has 3 plural forms, you'll
need msgstr[0], msgstr[1], and msgstr[2], and so on.
Sometimes (usually, even) the English strings will be the same. For
example, ``%d selected`` doesn't change whether it stands for *1 selected* or
*99 selected*. If it does in your language, you should translate them
differently. There are further difficulties for the many languages that
have gender agreement and an unspecified noun in the phrase, but these are
often translated with brackets (eg in French: *1 sélectionné(e)*, *99
sélectionné(e)s* perhaps)
Fuzzy translations
^^^^^^^^^^^^^^^^^^
A translation marked *fuzzy* is (usually) one that has been matched to a
similar previous translation, often by `gettext` itself. Note that fuzzy
translations are not treated as accurate translations so will not be used.
Common reasons for strings being marked as fuzzy include:
* A contributor corrects a typo in the source (English) text
* A developer changes the `Mnemonic Label
`_ -
This is the underscore you see in many translation strings.
* The English has changed, but not much
* sometimes it *just happens*...
For example::
#: ../quodlibet/browsers/albums.py:425
#, fuzzy
msgid "Sort _by:"
msgstr "Ordina per data"
Here, in the Italian `.po` file, you can see this message has been matched,
presumably used from a "Sort by date" translation previously entered. This
explains why this string was missing in the Italian build.
As a translator please make sure there are no translations left marked as
fuzzy. In `poedit`, you can click the cloud (!) icon, or in a text editor
you should simply remove the `fuzzy` string above the `msgid`.
quodlibet-3.9.1/docs/guide/ 0000755 0001750 0001750 00000000000 13115513301 015760 5 ustar lazka lazka 0000000 0000000 quodlibet-3.9.1/docs/guide/config_files.rst 0000644 0001750 0001750 00000004027 13112005742 021146 0 ustar lazka lazka 0000000 0000000 .. _ConfigFiles:
Configuration Files
===================
QL stores some of its configuration as plain text files, and in some cases
it may be convenient to edit these files directly, or to synchronize them
across different computers/ home directories.
Like many Linux applications, QL stores user configuration in a hidden
directory, in this case ``~/.quodlibet``. Feel free to explore; but maybe
make a backup of the directory first.
Saved values for search, tagging and renaming patterns
------------------------------------------------------
For :ref:`searching your library `, :ref:`editing tags from a
filename pattern `, and :ref:`renaming files based on tags
`, you can save the (search or pattern) values you enter for
later use. See the relevant section for how to do it using the GUI.
The patterns you create using "saved values" are in fact stored in simple
text files:
* ``~/.quodlibet/lists/queries.saved``:
Search patterns
* ``~/.quodlibet/lists/tagpatterns.saved``:
Patterns to tag files based on filename
* ``~/.quodlibet/lists/renamepatterns.saved``:
Patterns to rename files based on tags
You'll see that the format is very easy: Each saved pattern consists of two
lines, the first line contains the QL pattern, the second line its name.
The name may be identical to the pattern. The next saved "pattern -- name"
pair follows immediately on the next two lines.
Here's an example of what ``~/.quodlibet/lists/queries.saved`` might look
like::
artist = schubert
All by Schubert
artist = radiohead
All by Radiohead
&(genre = classical, #(lastplayed > 3 days))
&(genre = classical, #(lastplayed > 3 days))
~format = ogg
All ogg files
Or an example of a ``~/.quodlibet/lists/renamepatterns.saved``::
~/music///. >
Music from an album
~/music/misc/ -
Stray song
Just edit these files or synchronize them across computers or home
directories (for different users) as needed.
quodlibet-3.9.1/docs/guide/renaming_files.rst 0000644 0001750 0001750 00000012007 13112005742 021476 0 ustar lazka lazka 0000000 0000000 .. _RenamingFiles:
Renaming files
==============
Basic Syntax
------------
Quod Libet allows you to rename files based on their tags. In some cases
you may wish to alter the filename depending on whether some tags are
present or missing, in addition to their values. A common pattern might be::
.
You can use a ``|`` to only insert text when a tag is present::
. >
You can also specify literal text to use if the tag is missing by adding
another `|`::
|No Album> -
A reasonable use of albumartist would be::
||No artist>>
..which uses the first of the following: Albumartist, Artist or "No artist".
You can of course also move files across your filesystem to another
directory by mixing path elements and ```` syntax::
/home/*username*/Music///...
Simple Renames
--------------
Like tagging by filename, renaming by tags uses tag names enclosed by
``<...>`` to substitute values. To rename songs as their artist followed
by their title, use `` - `` (The file extension, .ogg, .mpc,
and so on, is automatically added). Other common patterns include
* ``. ``
* ``. - ``
* ``~/music/ - /. ``
* ``~/music///. ``
You can also use tied tags to rename, e.g. ````.
Creating Directories
--------------------
Note that if you use ``/`` (a directory separator) in your filename, you
''must'' start the pattern with a ``/`` (or a ``~/``, which expands to your
home directory). To see why, consider what would happen if you tried to
rename the same file twice with ``/``. The first time it
would go under ``Artist/Title.ogg``, the second time,
``Artist/Artist/Title.ogg``. When you specify the full path, this can't
happen.
If you don't use a `/` in the pattern, the file gets put in the same directory.
Conditional Renaming
--------------------
Consider the ``. `` pattern.
When the file is missing a track number, you get a filename that starts
with ., which isn't good. So Quod Libet lets you use ''conditional
renaming'' to avoid that.
To use conditional text, after the tag name (but inside the ``<...>``) put
a ``|`` (a pipe). Then after the pipe, place all the text you want,
including other tag names inside ``<...>``. That text will only be added when
that tag isn't empty.
To avoid the original problem, only display the track number, period, and
space when the track number tag exists:
``. >``.
Quod Libet also lets you change the text if a tag ''doesn't'' exist: Use a
second pipe. ``|00>. `` will use the
track number at the start of the filename if it exists, or *00* if it
doesn't.
Go crazy with conditions / More examples
----------------------------------------
So you basically want to remember that it goes ``|>`` You can however even put conditions inside each other.
Here's an example that I just created, and so far it seems to work:
I first had::
/mnt/musik//>|Unknown>//> - >
Let's dissect this:
* ``/mnt/musik``: My basic music partition
* ``/>``: If there is a tag "genre", put the song into that
folder (creating the folder if necessary). If there is no tag genre,
skip this level in the folder hierarchy (note that the trailing slash
of ``/`` is inside the < > that delineate the conditional "block".
* ``||Unknown>/``: If there's a tag artist, put everything
into that folder, else put into a folder called "Unknown". Not that the
trailing slash is outside the < > that delineate the conditional block,
since we always want that folder level.
* ``/>``: Album folder as needed, else skip
* ````: Prepend tracknumber if it exists
* ````: Duh.
However, for songs that don't have a genre tag, I wanted to use a tag I use
called "language" and sort into that folder instead. But I have some songs
that have a genre tag and also a language tag, and those songs should only
go into the genre folder; the language folder should be ignored.
Turns out QL can do this just fine, by expanding the ```` conditional
block in the expression above to ``/|/>>``.
Basically, the pipe after the second ``/`` introduces what should be
done if the first condition isn't met (i.e. no genre tag), but here instead
of putting straightforward text or another label we then introduce a second
conditional block, ``>``, which puts in a language tag
folder, if the song has a tag "language".
The full expression now looks like this::
/mnt/musik//|/>>|Unknown>//> - >
quodlibet-3.9.1/docs/guide/stats_rating.rst 0000644 0001750 0001750 00000002344 13112005742 021221 0 ustar lazka lazka 0000000 0000000 .. _Stats:
Library Statistics
==================
Play Count
----------
The internal ``~#playcount`` tag gets incremented after a song ends or is
forced to end by the user and the time it was played was more than half of
the song's duration.
In case of radio streams, which don't have a defined duration, the play
count gets incremented whenever the stream is played.
Searching for all songs that where played more than 10 times:
.. code-block:: text
#(playcount > 10)
Last Played Time
----------------
The ``~#lastplayed`` tag gets updated to the current time whenever
``~#playcount`` gets incremented.
Searching for all songs played less than 4 days ago:
.. code-block:: text
#(lastplayed < 4 days)
Last Started Time
-----------------
The ``~#laststarted`` tag gets updated to the current time whenever the
song gets started.
Searching for all songs started less than 1 week ago:
.. code-block:: text
#(laststarted < 1 week)
Skip Count
----------
The ``~#skipcount`` tag gets incremented whenever the song gets forced to end
by the user and the playing time was less than half of the song's duration.
Searching for songs that where skipped between 5 and 10 times:
.. code-block:: text
#(5 <= skipcount <= 10)
quodlibet-3.9.1/docs/guide/tags/ 0000755 0001750 0001750 00000000000 13115513301 016716 5 ustar lazka lazka 0000000 0000000 quodlibet-3.9.1/docs/guide/tags/index.rst 0000644 0001750 0001750 00000000141 13112005742 020555 0 ustar lazka lazka 0000000 0000000 Tags
====
.. toctree::
:titlesonly:
tags
internal_tags
tied_tags
patterns
quodlibet-3.9.1/docs/guide/tags/internal_tags.rst 0000644 0001750 0001750 00000013005 13112005742 022303 0 ustar lazka lazka 0000000 0000000 .. _InternalTags:
Internal Tags
=============
Quod Libet stores a number of tags internally, that are either not stored
in files themselves, or are derived from the values in the files.
String Tags
-----------
* ``~basename``: The last component of the full path name
* ``~dirname``: Everything but the last component of the file path name
* ``~filename``: The full path name
* ``~format``: The file format (e.g. "MPEG-4")
* ``~codec``: The audio codec (e.g. "AAC LC")
* ``~encoding``: Encoder name, version, settings used (e.g. "LAME 3.97.0, VBR")
* ``~length``: The length of the file in H:MM:SS format
* ``~mountpoint``: The component of the full path name that corresponds to the file's immediate parent mount
* ``~performers``: A list of performers
* ``~people``: A list of all people involved in the song
* ``~rating``: A string representation of the song's rating (e.g. ★★★☆). Note that in most formats these are per email address.
* ``~uri``: The full URI of the song
* ``~year``: The release year, derived from the ``date`` tag
* ``~originalyear``: The original year, derived from the ``originaldate`` tag
* ``~playlists``: Comma-separated playlist names in which the song is included
* ``~filesize``: Human formatted size (e.g. *4.5 MB*)
The ``~people`` Internal Tag
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The internal ``~people`` tag combines the following tags to one:
``albumartist``, ``artist``, ``author``, ``composer``, ``~performers``,
``originalartist``, ``lyricist``, ``arranger``, ``conductor`` in this exact
order.
For sorting, this means that all album artists come first followed by
all artists and so on. For song collections / albums, the values of
each included tag are sorted by frequency.
Variants:
``~people:roles`` includes roles e.g. ``"The Parley of Instruments
(Orchestra), David Thomas (Bass)"``. The roles are either derived from the
source tag name (``composer=Joseph Haydn`` → ``Joseph Haydn
(Composition)``) or from the performer role
(``performer:composition=Joseph Haydn`` → ``Joseph Haydn (Composition)``).
For the latter see the ``~performers`` tag.
``~people:real`` excludes *Various Artists*, commonly used as a
placeholder for album artists on compilations, etc.
The ``~performers`` Internal Tag
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The internal ``~performers`` tag combines all the artists specified in the
performer tags to a single one.
Example: ``performer:vocals=Brandon Patton, performer:banjo=Béla Fleck``
``~performers`` will then display ``"Brandon Patton, Béla Fleck"``
Variants:
``~performer:roles`` includes the roles as well. For the above example
it will display ``"Brandon Patton (Vocals), Béla Fleck (Banjo)"``
Song Collections / Albums
^^^^^^^^^^^^^^^^^^^^^^^^^
* ``~length``: The length of all songs in H:MM:SS format
* ``~long-length``: The length of all songs in "H hours, M minutes, S seconds" format
* ``~tracks``: The real number of songs in the collection in "# track(s)" format
* ``~discs``: The number of different discs in "# disc(s)" format
* ``~rating``: The average rating in music notes
* ``~filesize``: Total Human formatted size (e.g. *4.5 MB*)
All other tags return a list of values retrieved from all songs, without
duplicates, sorted by their number of appearance.
.. _numeric-tags:
Numeric Tags
------------
* ``~#added``: The date the song was added to the library
* ``~#bitrate``: The bitrate of the song, in kilo bits per second
* ``~#disc``: The disc number of the song (the first half of the ``discnumber`` tag)
* ``~#channels``: The channel count
* ``~#discs``: The total number of discs in this song's collection
* ``~#filesize``: The size in bytes of this song
* ``~#lastplayed``: The time this song was last played through
* ``~#laststarted``: The time this song was last started
* ``~#length``: The length of the song, in seconds
* ``~#mtime``: The time this file was last modified
* ``~#playcount``: The total number of times you've played the song through
* ``~#rating``: The rating of the song, as a number between 0 and 1.
* ``~#skipcount``: The total number of times you've skipped through the song
* ``~#track``: The track number of the song (the first half of the ``tracknumber`` tag)
* ``~#tracks``: The total number of tracks in the album
* ``~#year``: The release year, derived from the ``date`` tag
* ``~#originalyear``: The original year, derived from the ``originaldate`` tag
Note some numeric tags have string tag equivalents (see above) for
human-readable format.
Song Collections / Albums
^^^^^^^^^^^^^^^^^^^^^^^^^
* ``~#tracks``: The real number of songs in the collection
* ``~#discs``: The number of different discs in the collection
For all other numeric tags it is possible to define numeric functions by
appending ``:numeric_func`` to the tag name (``~#playcount:avg`` for example).
All internal numeric tags use a default function in case no function is
given. For user defined numeric tags the average value is returned by
default.
* ``avg``: Returns the average value (``~#rating``)
* ``sum``: Returns the summation of all values (``~#length``, ``~#playcount``, ``~#skipcount``, ``~#filesize``)
* ``min``: Returns the smallest value (``~#year``)
* ``max``: Returns the largest value (``~#added``, ``~#lastplayed``, ``~#laststarted``, ``~#mtime``)
* ``bav``: Returns the `Bayesian average `_ value (``~#rating``)
Being most appropriate for ratings, the parameter is adjusted
globally under the preferences for ratings.
quodlibet-3.9.1/docs/guide/tags/patterns.rst 0000644 0001750 0001750 00000006677 13112005742 021332 0 ustar lazka lazka 0000000 0000000 Tag Patterns
============
Tag patterns allow more complex string representation of tags, with a
notion of if-null defaulting; whilst this sounds complex (and it can be!)
it's very useful where libraries have wildly varying tags.
Tag patterns can include strings (e.g. tag names) enclosed in angled
brackets like this
`` - ()``
Which might produce:
``The Beatles - Drive My Car (Rubber Soul)``
Usage
-----
Tag patterns in QL can be used to change the information displayed in various
places, like the playing song area, columns in the song list and the album list
in the album browser.
They can be used to group songs in the paned and the album collection
browser in more complex ways.
And, of course, tag renaming based on tags uses tag patterns to create
the file names and folder structure.
Conditional Tags
----------------
A simple if-then-else concept can be used in tag patterns, testing if a tag
is non-empty. The syntax uses the pipe (``|``) character as a delimiter, in
either of these formats:
* ```` or
* ````
So using the full (second) form, a Pattern of:
````
produces *Has An album* for any song with at least one ``album`` tag value,
else *No Album*.
Note that these can be recursive, i.e. both `non-empty-value` and
`empty-value` are themselves tag patterns, which could contain a
conditional. A more useful example now:
``|>``
This will look for the ``albumartist`` tag and display that if available,
else use ``artist`` (nearly always available).
Examples:
* ``<~year|<~year>. |>``: *2011. This is an album title*
* ``, by ||>>``:
*Liebstraum no. 3, (by Franz Liszt)*
Conditional Tags With Comparisons
---------------------------------
In addition to checking if a tag value is empty, the "if" expression can also
contain a value comparison using the same syntax as the :ref:`search
`:
````
or more complex ones (note the needed escaping):
````
Text Markup
-----------
In some situations the resulting text will be displayed in the user
interface like for example the album list or the area which displays
information about the currently playing song. To style the resulting text
you can use the following tags in combination with the tag patterns.
===================== ==========
Tag Result
===================== ==========
``[b]..[/b]`` Bold
``[big]..[/big]`` Bigger
``[i]..[/i]`` Italic
``[small]..[/small]`` Smaller
``[tt]..[/tt]`` Monospace
``[u]..[/u]`` Underline
``[span][/span]`` see below
===================== ==========
The ``span`` tag can define many more text attributes like size and color:
``[span size='small' color='blue']..[/span]``. See the `Pango Markup
Language`_ page for a complete list of available attributes and values.
A complete example might look like this:
::
[span weight='bold' size='large'][/span]<~length| (<~length>)> : [b]<~rating>[/b][/b][/small]><~people|
by <~people>>>>
Note also the literal newlines.
.. _`Pango Markup Language`: https://developer.gnome.org/pango/stable/PangoMarkupFormat.html
quodlibet-3.9.1/docs/guide/tags/tags.rst 0000644 0001750 0001750 00000006175 13112005742 020421 0 ustar lazka lazka 0000000 0000000 .. _AudioTags:
An Introduction to Tags
=======================
Overview
--------
Quod Libet supports free-form tags for most of the common audio formats.
This means you can name your tags in any way you want, but using common tag
names for common purposes is advised because it helps QL to write the tags
in a way that other media players can understand them and also helps QL
understand certain tag values and make use of them.
Quod Libet also supports expressions using "tied tags" in several contexts
- see :ref:`TiedTags`
Sort Tags
---------
Tags ``artistsort``, ``albumsort``, ``albumartistsort``, ``performersort``
(including roles) will be used for sorting if they are present.
Lets say you have a song with an ``artist`` tag *The Beatles* and want it
to be sorted as if it was named *Beatles, The*, you can add an
``artistsort`` tag containing *Beatles, The*.
* QL includes a basic plugin for creating such sort tags automatically.
* The musicbrainz plugin includes an option to write sort tags if found.
Programmatic Tags
-----------------
A programmatic tag is one typically added by either Quod Libet / Ex Falso or
another program and not designed for human consumption. Examples are
``replaygain_track_gain`` or ``musicbrainz_albumid``. Note that to see
these, you must turn on "Show programmatic tags" in the relevant
preferences window.
Internal Tags
-------------
Internal tags are tags that start with a ``~`` like ``~people``, ``~length`` or
``~year``. They are either not stored in files themselves, or are derived
from the values in the files.
See :ref:`InternalTags` for a complete list.
.. _PerformerRoles:
Performer Roles
---------------
Quod Libet supports performer roles, which let you associate a performer in a
song with a specific instrument. To use this feature, name a tag
performer:role. Quod Libet will display the roles alongside the names in
``~people:roles`` and ``~performers:roles``.
Album Identification
--------------------
Quod Libet uses various tags to define what songs are in the same album.
For songs to be in the same album, both ``album`` and ``albumartist`` have to
be the same. In addition the first non-empty value of the following tags have
to match (checked in this order): ``musicbrainz_albumid``, ``labelid``,
``album_grouping_key``.
Common scenarios
^^^^^^^^^^^^^^^^
''I have a two disc album and each disc is shown separately.''
Make sure the album tags (and ``albumsort`` if present) (remove 'CD1/2' etc.)
and albumartist tags are the same.
''Two albums have the same name and are merged.''
Add an albumartist tag for at least one of them.
Common Questions
^^^^^^^^^^^^^^^^
''Why doesn't QL know that my albums are different ones by seeing that they don't have the same artist?''
There are many songs that have multiple artist, so this can't be decided on the basis of artist tags.
Replay Gain Tags
----------------
The following (fairly standard) tags are used for volume adjustment:
* ``replaygain_track_gain``
* ``replaygain_track_peak``
* ``replaygain_album_gain``
* ``replaygain_album_peak``
See the :ref:`Replay Gain ` section for further details.
quodlibet-3.9.1/docs/guide/tags/tied_tags.rst 0000644 0001750 0001750 00000002362 13112005742 021420 0 ustar lazka lazka 0000000 0000000 .. _TiedTags:
Tied Tags
=========
Tied tags are expressions to produce a readable formatted output of more
than one tag. Tag values are outputted left to right, with the default
output separator as ``-``. To combine multiple tags start the expression
with ``~`` and separate each tag by ``~`` again.
Examples:
============================== ================================ =========================================================
Included Tags Tied Tag Result
============================== ================================ =========================================================
artist, title ``~artist~title`` *Bob Marley - Jammin'*
~#track, ~dirname ``~~#track~~dirname`` *5 - /home/user/music/Reggae*
date, artist, album, ~filesize ``~date~artist~album~~filesize`` *2000 - Bob Marley - Songs of Freedom (Various) - 6.9 MB*
============================== ================================ =========================================================
Usage in Quod Libet
-------------------
Tied tags can be used in tag patterns and searches as if they were normal
tags:
::
~artist~title=/AC.?DC/
::
. >
quodlibet-3.9.1/docs/guide/overview.rst 0000644 0001750 0001750 00000011420 13112005742 020360 0 ustar lazka lazka 0000000 0000000 Overview
========
The Fundamentals
----------------
Explanation of the GUI elements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When you start up Quod Libet for the first time, and have configured your
library, it should look something a little like the screenshot here, which
is show with annotations. These are all explained below.
.. figure:: images/main_overview.png
:align: right
:width: 400px
:figwidth: 400px
A basic view of Quod Libet, and its GUI elements
1. Player Controls
^^^^^^^^^^^^^^^^^^
Provides buttons for seeking, changing volume and changing the currently played song.
By right-clicking, they also provide context menus with advanced options:
* The volume button lets you choose the active replaygain mode
(album, track, automatic).
* The seek button can display the remaining instead of the elapsed time
and provides options for interacting with bookmarks.
* The context menu of the play button has an option to pause playback after
the current song.
2. Current Song Information
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Displays information about the currently playing song.
Again, the context menu contains more options, like rating and tag editing
for the current song.
There is also an entry called *Edit Display...* which lets you change
everything that is shown in that area, like the file format, bitrate, font
size etc. The syntax is the same as for :ref:`renaming files `.
3. The Song List & Browser
^^^^^^^^^^^^^^^^^^^^^^^^^^
As the name suggests, the song list is a list of matching songs presented
by the current browser. The browser consists of a way to filter your
library (songs), e.g. a simple search or by a list of albums. In the image
above, no browser is active so only the current song list is shown. You can
change the active browser by selecting one in the *View* menu.
4. Playback Order
^^^^^^^^^^^^^^^^^
The active playback order affects the selection of the next song or what
happens if you manually switch to a new song.
Note that Play Order Plugins add to this list allowing QL new ways of
ordering songs, like following your selection or adding songs to the queue
instead of playing them immediately.
The *Repeat* checkbox can be used in conjunction with the playback orders,
to repeat the currently selected view of songs after all song have been
played or skipped.
It's important to note that the playback order will not affect the queue,
which has its own playback settings.
5. Song Information
^^^^^^^^^^^^^^^^^^^
The area in the bottom-right corner shows information about all songs in
the song list *or* about your song selection if more than one song is
selected.
It also shows progress information of background operations like importing
music.
The Queue
---------
.. image:: images/queue.png
:width: 350px
:align: right
The play queue and the song list determine what's played next. Unlike the
song list the queue consumes songs (from the queue not your library) as
they are played. That is, once a song starts playing it disappears from the
queue.
The queue however, takes precedence whenever it has songs. After it's empty,
playback will continue in the main song list where it left off.
To add songs to the queue, right-click and *Add to Queue*, use the shortcut
``CTRL+Return`` or select songs in a different browser window.
More Browsers
-------------
.. image:: images/browser_window.png
:width: 350px
:align: right
Besides the active browser in the main window, you can open as many
different browser windows as you want by selecting one under *Browse* >
*Open Browser* or in the tray icon plugin context menu.
In a separate browser, double-clicking a song will result in it being
added to the queue rather than played immediately (as per the main browser).
See the :ref:`Browsers Guide ` for full details on browsers and the
various implementations.
Example usage:
* Manage playlists by dragging songs across browsers (eg Search browser to Playlist browser)
* Edit the tags of some songs while the ones in the main song list get played etc.
* Check out other songs by the artist currently playing without disturbing that list.
The Library
-----------
If all your music lives in one folder on your computer, adding your entire
music collection in Quod Libet is easy.
From the main menu bar, select *File* > *Add a Folder* and browse to the
top-most folder containing your music. By default Quod Libet will scan
your selected folder recursively, adding all the songs found to your
library automatically. Add more folders if you wish.
Depending on the size of your music collection, it may take a few minutes
to perform the initial scan.
Plugins
-------
.. image:: images/plugins.png
:width: 450px
The image above shows the plugin manager, from where you can enable /
disable / configure all available plugins.
quodlibet-3.9.1/docs/guide/searching.rst 0000644 0001750 0001750 00000015435 13112005742 020467 0 ustar lazka lazka 0000000 0000000 .. _Searching:
Searching Your Library
======================
Pretty much every view in Quod Libet contains a search entry where you can
enter search terms and save them. Quod Libet will search in artist, album,
title, version, and any other visible columns for what you enter.
If that's enough for you, you can stop reading now. But what if you want
something more powerful?
Combining Searches and Negation
-------------------------------
You can combine search terms using ``&`` ("and") and ``|`` ("or").
If you want to listen to Electronic music but no Ambient::
&(electro, !ambient)
Or you want to get all songs by `Neutral Milk Hotel
`_ including the solo
performances of `Jeff Mangum `_::
|(mangum, neutral milk)
You can get all songs that don't match the search term using ``!``::
!electro
Lets say you want to listen to you whole library but are not in the mood
for classical music or songs by `The Smiths
`_::
!|(classical, smiths)
While these searches are easy to type in, they depend on the visible columns
and the active browser, also the last one might exclude some songs which
happen to contain "smiths" in their album title
- see below for how to perform more targeted searching.
Searching a Specific Tag
------------------------
To search a specific tag, use a search like::
artist = delerium
album = bargainville
The search terms can't use quotes (``"``), slashes (``/``), hashes (``#``),
pipes (``|``), ampersands (``&``), or bangs (``!``); these characters have
special meanings for advanced searches.
In QL 3.9 onwards, you can also use `!=` to search for things not equal::
artist != delerium
genre != /.+ Jazz/
You can also search :ref:internal tags , e.g.
* ``~format = Ogg Vorbis``
* ``~dirname=Greatest Hits`` - search for all songs in Greatest Hits folders.
It's also possible to search in multiple tags at once:
* ``artist, performer = "Boa"c``
Exact Matching
--------------
If you want an exact match, use quotes::
artist = "a girl called eddy"
If you need to put a ``"`` inside the quotes, you can put a ``\`` before it::
version = "12\" mix"
You can put a ``c`` after the last " to make the search case-sensitive::
artist = "BoA"c
artist = "Boa"c
artist != "Boa"c
Combining Tag Searches
----------------------
As with free-text searches, you can combine searches using ``&`` ("and") and
``|`` ("or"); either grouping entire searches, or just the tag values.
Although the examples below use simple keywords, you can also use exact
matches or regular expressions::
artist = |(Townshend, Who)
&(artist = Lindsay Smith, album = Vat)
The first finds anything by `The Who `_
or guitarist `Pete Townshend `_
. The second gives the songs that match both, so you'll find songs `Lindsay
Smith `_'s `Tales From The Fruitbat Vat
`_, but not her other albums.
You can also pick out all the songs that *don't* match the terms you give,
using ``!``::
genre = !Audiobook
is probably a good idea when playing your whole library on shuffle.
Note again that in QL 3.9 onwards you can use the alternative syntax of::
genre != Audiobook
Numeric Searches
----------------
Using ``#``, you can search your library using numeric values. Quod Libet
keeps some internal numeric values including ``track``, ``disc``,
``rating``, ``length`` etc. See :ref:`numeric-tags` for full details. You
can also search any other tag as long as the values have a number format
like ``1234`` or ``-42.42``, for example ``year`` or ``bpm``.
For comparisons you can then use typical binary operators like ``=``,
``<``, ``>``, ``<=``, ``>=`` and ``!=``.
* ``#(skipcount > 100)`` could find really unpopular songs, or
* ``#(track > 50)`` to figure out who makes really insane albums, or
* ``#(bpm > 160)`` to find really fast songs
You can also use chained comparisons:
* ``#(10 <= track < 100)`` to find all two-digit tracks.
Times like ``added`` are stored in seconds, which is pretty cumbersome to
search on. Instead, you can search with semi-English,
like:
* ``#(added < 1 day)`` for very recently added tracks
to find songs added in the last day (if you think that that's backwards,
mentally add 'ago' when you read it). Quod Libet knows about seconds,
minutes, hours, days, months (30 days), and years (365 days), kB
(Kilobyte), MB (Megabyte), GB (Gigabyte). You can also use ''HH:MM''
notation, like:
* ``#(2:00 < length < 3:00)`` for songs between two and three minutes long.
Of course, you can combine numeric with other kinds of searches.
* ``&(genre = classical, #(lastplayed > 3 days))``
* ``&(artist = "Rush", #(year <= 1996))``
Playlists
---------
You can use the ``~playlists`` internal tag to search by playlists. It is
populated with a list of all the playlists that song appears in. This is
surprisingly powerful if you're a playlist user.
* ``~playlists=chilled`` will return all songs included in any playlist
with "chilled" in its name.
* ``~playlists=|("Chilled", "Jazzy")`` for all songs in either (or both)
of those playlists.
* ``&(#(rating>=0.75), ~playlists="")`` will return all high-rated songs
*not* in any playlist
Regular Expressions
-------------------
Quod Libet also supports searching your library using ''regular
expressions'', a common way of finding text for Unix applications. Regular
expressions look like regular searches, except they use / instead of ", and
some punctuation has special meaning. There are many good tutorials on the
web, and useful online regex testers (such as `Regex Pal `_)
Some examples:
* ``artist = !/\sRice/`` (or in 3.9+: ``artist != /\sRice/``)
or using the default tags
* ``/^portis/``
like with exact matches append a `c` to make the search case-sensitive
* ``/Boa/c``
Ignore Accents and Umlauts
--------------------------
Appending a ``d`` after searches makes it's characters match variants with
accents, umlauts etc.
Both ``/Sigur Ros/d`` and ``"Sigur Ros"d`` will match songs with the artist
name ``"Sigur Rós"``.
Now you can search anything!
Reusing queries
---------------
Complex queries can be split into simpler ones. Also, a query can be reused
in other ones. This way it is easier to change and administer your searches.
In order to do so, the ``Include Saved Search`` plugin must be activated.
If you create a saved search named ``Unrated`` you can search for unrated songs from the Beatles
like this:
``&(@(saved: Unrated), Beatles)``
For creating saved searches, use the "Edit saved searches..." item in the drop-down
at the right of the query text box.
quodlibet-3.9.1/docs/guide/index.rst 0000644 0001750 0001750 00000000407 13112005742 017624 0 ustar lazka lazka 0000000 0000000 User Guide
==========
.. toctree::
:titlesonly:
overview
tags/index
searching
stats_rating.rst
browse/index
editing_tags
renaming_files
playback/index
shortcuts
interacting
config_files
commands/index
faq
quodlibet-3.9.1/docs/guide/interacting.rst 0000644 0001750 0001750 00000007507 13112005742 021034 0 ustar lazka lazka 0000000 0000000 Interacting with Quod Libet
===========================
In Python
---------
Quod Libet supports :ref:`plugins written in Python `. These
plugins can interact with songs more directly than the other interfaces,
changing or reading metadata using dict-like !AudioFile objects. The plugin
interface has not yet stabilized, although we do not expect it to change
drastically in the future.
The Unix Way
------------
Querying the player
^^^^^^^^^^^^^^^^^^^
Quod Libet writes information about the current song to
``~/.quodlibet/current``. The file is in key=value form. Key values are in
UTF-8, except for the ``~filename`` key, which has unknown encoding (but
will point to the file being played when interpreted as a sequence of bytes).
There is a ``--print-playing`` option which can use the same syntax as the
RenamingFiles interface to print information about the current song:
``quodlibet --print-playing ' - '``
``quodlibet --status`` provides player state information. The first word
will be either *playing*, *paused*, or *not-running*, followed by
* the selected View,
* volume setting (0.0 - 1.0)
* Playback order & repeat settings
If the View is SearchBar, then the text currently in the search bar will be
displayed on a second status line.
Controlling the player
^^^^^^^^^^^^^^^^^^^^^^
Quod Libet understands a number of command line arguments to control a running player. For a full list, see the man page.
* ``--next``, ``--previous``, ``--play``, and ``--pause`` should
be self-explanatory; ``--play-pause`` toggles pause on and off.
* ``--volume n`` sets the volume to anywhere between 0 (muted) or
100 (full volume)
* ``--seek