Collections usage with cli

Introduction

This is a quick introduction to working with Collections using the CLI client. If you don't know what a collection is, you might want to read the Collections Concept page.

In short, a collection is a subset of the medialibrary. It therefore matches (or "contains") a set of media. From there, it can be used for many purposes, from organizing your music to feeding random playlist.

Collection structure and pattern

A collection is represented as a graph structure composed of group operators (union, intersection, complement), filters on properties (match, has, etc) and static list of media. The topography of such a structure can be very complex, and is not necessarily easy to expose to the user. An advanced pattern syntax has been devised to provide as much freedom as possible in that regard.

Its grammar may scare the faintest hearts, and another page will be written to describe in details the syntax of the patterns. For now, you can simply stick to the following, simple use of the pattern syntax:

PATTERN := FILTER PATTERN FILTER := property:value | value | ø

where property is the name of any media property (artist, album, tracknr, etc). If the property is omitted, the value is searched in several common fields (artist, album, title). A value string can contain "*" and "?" wildcards.

Here are examples of valid patterns:

artist:"Pink Floyd" artist:Air album:"Talkie Walkie" album:"Scorpio Rising" tracknr:5 year:2002 Talisman (year<2000 OR l:*live*)

We will now show how to use the collection commands of the CLI. To get some help, you can simply type:

% xmms2 help collection usage: xmms2 collection [args] Available 'collection' subcommands: list show create rename remove config

Save a collection

Now we have a way to represent a collection structure, we may want to use it against the media library. First, let's create our collection on the server:

% xmms2 collection create AirFirstTracks artist:Air tracknr:1

This creates a new collection named AirFirstTracks that matches all first tracks of albums by Air. The syntax of the create command is the following:

% xmms2 collection create

Collections on the server are partitioned in namespaces, and they can be created in any of them. By default, the Collections namespace is selected, but collections in other namespaces can be referred to as collname using the namespace/ prefix:

AirFirstTracks # equivalent to Collections/AirFirstTracks Collections/"Foo collection" Playlists/GreatPlaylist

However, only idlists can be created in the Playlists namespace, so it is not possible to save one of our dynamic collection structures (based on filters) in that namespace.

More Complicated Collection Queries

It is possible to create far more complicated collections. Note that the values return by a "search" call are the same values that will go into a collection using that query with a "collection create" call. Also, all searches are case insensitive.

Finds all songs with either artist; similarily for AND and NOT.

% xmms2 search "artist:Mr. Scruff" OR "artist:Mr. Crispy"

Finds all songs where the artist has "a" in the name, and the song title has "b".

% xmms2 search artist:'*a*' AND title:'*b*'

All songs that have any value at all in the "rating" property.

% xmms2 search +rating

All songs that have a rating less than or equal to 5, and similarily for >=, <, and >.

% xmms2 search 'rating<=5'

Song id number 18 only.

% xmms2 search '#18'

which is equivalent to

% xmms2 search 'id:18'

All songs in the collection test1

% xmms2 search in:test1

Example of grouping; all artist-has-a and title-has-b songs, plus all songs where the artist is PPK. NOTE: Grouping does not properly in release vesions before DrKosmos.

% xmms2 search '(' artist:'*a*' AND title:'*b*' ')' OR artist:PPK

Rename a collection

In case you want to rename a collection saved on the server, you can simply use the rename command:

% xmms2 collection rename Foo Bar % xmms2 collection rename Playlists/GreatPlaylist Playlists/AwesomePlaylist

The syntax of that command is straightforward:

% xmms2 collection rename

Note that this syntax is different from the playlist command.

Again, the namespace can be specified as a prefix. It must however be noted that you cannot move a collection from one namespace to another, and the following command is invalid:

% xmms2 collection rename AirFirstTracks Playlists/AirPlaylist # invalid!

List saved collections

After you have saved a couple of collections on the server, you may want to list them all. This can be done using the list command:

% xmms2 collection list AirFirstTracks Test Collection

To list saved playlists:

% xmms2 playlist list

View the structure of a saved collection

The list only gives us the name of the saved collections, but you may want to check what the corresponding collection structure looks like. This can be done using the show command:

% xmms2 collection show AirFirstTracks Intersection: Match ('artist', 'Air') for: Reference: 'All Media' Match ('tracknr', '1') for: Reference: 'All Media'

Again, we can refer to collections in other namespaces using the usual prefix:

% xmms2 collection show Playlists/Other Idlist: (14461, 14462, 7226)

List the contents of a collection

Now we have played with collections, it might be interesting to actually display what media they match, i.e. their contents. For that, we use the search command:

By default, media are ordered by id. You can change that by selecting a list of ordering properties:

Add a collection to the active playlist

To add the contents of a collection to the active playlist use:

% xmms2 add in:''

Remove a collection

If you have had enough of a collection, you can just remove it:

% xmms2 remove AirFirstTracks

Note that if you any other collection had a reference to a collection you remove, the reference will be replaced by the actual structure of the removed collection, thus keeping other collections intact.

The syntax of the remove command is the following:

% xmms2 collection remove

Find collections matching a given media

It is also possible to perform the inverse of query, that is to find all collections that match a given media. This is done using the find command:

% xmms2 collection find 181 * Playlists Namespace: * Collections Namespace: AirFirstTracks

If we want to restrict the search to one namespace, we simply append it as an argument:

% xmms2 collection find 181 Collections AirFirstTracks

The syntax of the find command is the following:

% xmms2 collection find [namespace]

Changing the type of a playlist

Playlists have a type, which can be one of the following:

list: a normal static list.
queue: a list where songs are popped once they are played.
pshuffle: a Party Shuffle is a queue which is automatically padded with new songs randomly fetched from a given collection.

To learn more about these types, read the section about List Operators.

To get the type of a playlist, use the config subcommand of the playlist command:

% xmms2 playlist config Playlist name: Playlist type: list

We can change the type to queue using the same command:

% xmms2 playlist config --type queue Playlist

For the pshuffle type, the source collection (input operand) of the shuffle must be specified:

% xmms2 playlist config --type pshuffle --input AirFirstTracks Playlist % xmms2 playlist config name: Playlist type: pshuffle history: (null) upcoming: (null) input: Collections/AirFirstTracks

The playlist has been filled with 10 random media from the AirFirstTracks collection. To change that number repeat the config command with the --upcoming option followed by the number of tracks. You can also use the collection config command, but it's hardly worth the trouble.

Setting attributes

Collection operators can have arbitrary attributes. Some have a special meaning depending of the context or the type of operator. One particular example is the attributes of queue and pshuffle playlists: both have a history attribute that specifies how many entries are kept after being played before they are popped; the pshuffle also has an upcoming attribute that specifies how many upcoming entries are to be fetched from the source collection.

We can use the attr command of the CLI to get and set attributes of saved collections. First, let's list all the attributes of a collection:

% xmms2 collection attr Playlists/Other [position] -1 [size] 10

You can also limit the output to a single attribute by specifying it as an extra argument:

% xmms2 collection attr Playlists/Other size [size] 10

The position and size attributes are internal attributes for collections used as playlists, and you shouldn't change them directly. However, let's set the upcoming attribute to 3:

% xmms2 collection attr Playlists/Other upcoming 3

We can see the effect if we reinitialize the playlist:

% xmms2 clear Other % xmms2 list Other ->[0/192] Air - Modular mix (05:59) [1/102] Air - Playground Love (03:32) [2/142] Air - La Femme D'Argent (07:11)

You can experiment some more by setting the history attribute for queue and pshuffle playlists.

End Credits

This is merely an introduction to the possibilities offered by collections in XMMS2. You are welcome to explore more possibilities in your own client or come on IRC to bother theefer about bugs or broken ideas!

Content is available under GNU Free Documentation License 1.2 unless otherwise noted.

Privacy policy, About XMMS2, Disclaimers