New korving CLI - nesciens/xmms2-wiki GitHub Wiki

This page is for discussion of a new potential CLI client for XMMS2.

• scripting/alias support
  • alias dis="clear;mlib searchadd artist:dismantled;play"
• shell functionality (including clever completion)
• depending calls
  • mlib search artist:foobar; add (will search after foobar and add without arguments will use the last returned list)
• pipe support
  • cat file.m3u | xmms2 add
• better argument parsing
  • xmms2 add -p playlist
• short commands
  • either as default completion ("ju" matches only "jump") or using chosen one- or two-letter shortcuts (e.g. 't' == "status")
• wide use of transient collections / patterns
  • i.e. never require to save a collection before it can for instance be used as input for a Party Shuffle; allow the use of a pattern directly.

• minimal dependency, glib and readline? (maybe libedit, seems more sane than readline)
• have some compatibility with old cli but not to death either.

Much of the commands are inspired both from the current cli and from nyello. The client can either be used inline (xmms2 play) or as a shell, if started without arguments:

$ xmms2 xmms2> next xmms2> play

The prompt should be configurable with a custom string that could contain variables such as the current playlist, playback status, current song, etc.

help    [command] quit play pause stop    [options] seek               <time|offset> prev    [offset] next    [offset] jump    [options]   search  [options]   info                list    [options]  [pattern] add     [options]   remove  [options]   move    [options]   status  [options] playlist    list               [pattern]   switch                create  [options]     rename  [options]     remove                config  [options]   clear              [name]   shuffle            [name]   sort    [options]  [name] collection    list    [options]  [pattern]   save    [options]     rename  [options]     remove  [options]   attribute [options]    server    browse                import                rehash             [pattern]   remove             [pattern]   property [options] [mid [key [value]]]   config             [key [value]]   volume  [options]  <value|offset>   stats   plugins   quit

Without argument, prints the list of commands with description; with an argument, it prints the detailed usage of the command. If command is an alias print alias definition. It is equivalent to running command -h or command --help.

Options:  -a, --alias List aliases, or alias definition.

If used in shell-mode, exits the client. In inline mode, it does not do anything.

Starts playback.

If pattern is given, do the same that "xmms2 jump && xmms2 play" would do (ie, don't play if pattern doesn't work).

I'd rather do this kind of function using aliases, if possible (so you could also have addplay, etc). --Theefer 08:44, 20 August 2007 (CEST) Or alternatively, replace the jump command with the play command. But that makes it impossible to jump without playing, which could be annoying. Worth trying still. --Theefer 04:24, 21 August 2007 (CEST)

Pauses playback.

Stop playback, possibly after a delay specified by the options.

Options: -n, --tracks   Number of tracks after which to stop playback. -t, --time    Duration after which to stop playback.

Note: maybe these options should not be here, but managed by a service client?

Seek in the current track, either using an absolute position or a relative offset (if prefixed by + or -). The argument is always a time value. If the resulting position is before the beginning or after the end of the current track, the seeking continues in the adjacent tracks.

Advance backward or forward in the playlist. By default, the step is one track, unless an offset (single integer value) is specified.

Jump to the first track after the current track matching the pattern.

Options: -b, --backward   Jump to the first track matching the pattern backwards.

Search and print all the media matched by the pattern. Search can be restricted to a collection or a playlist by using the corresponding flag.

Options: -p, --playlist              Search in the given playlist. -c, --collection            Search in the given collection. -o, --order <prop1[,prop2...]>    List of properties to order by                                   (prefix by '-' for reverse ordering). -l, --columns <prop1[,prop2...]>  List of properties to use as columns.

Display all the properties for each media matched by the pattern.

List the contents of the active playlist by default. This command can also be used to display any other playlist (see Options).

If a pattern is given, contents are further filtered and only the matching media are displayed.

Options: -p, --playlist     Display a given playlist.

Add the matching media to a playlist or a collection. Some options are only relevant when adding to playlists or collections.

This command can also be used to add files using their URI. By default, directories are added recursively.

Options: -f, --file               Treat the arguments as file paths, not a pattern. -P, --pls                Treat the files as playlist files (implies --file.) -N, --non-recursive      Do not add directories recursively. -p, --playlist     Add to a given playlist. -n, --next               Add media after the current track. -a, --at <pos|offset>    Add media at a given position in the playlist,                          or at a given offset from the current track. -c, --collection   Add to a given collection. -s, --static             Add matching media as a static list of entries,                          rather than a dynamic filter.

Note: there's a GUESS_PLS option in configuration file; if set it will add playlist files without -P option

Note: --static might not be needed; add should probably add "all media matching the pattern" to the playlist or the collection, and another (collection) command should be used to "augment" or modify the dynamic pattern of a saved collection.

Remove the matching media from a playlist or a collection. Some options are only relevant when adding to playlists or collections.

Options: -p, --playlist     Remove from a given playlist. -c, --collection   Remove from a given collection. -s, --static             Remove matching media as a static list of entries,                          rather than a dynamic filter.

Note: See remark about --static for the add command.

Move entries inside a playlist, by default the active playlist.

Options: -p, --playlist   Playlist to act on. -n, --next             Move the matching tracks after the current track. -a, --at <pos|offset>  Move the matching tracks by an offset or to a position.

Display the current status of the server.

Options: -r, --refresh   Delay between each refresh of the status; if 0,                       the status is only printed once (default). -f, --format  Format string used to display status.

List all the existing playlists. If a pattern is provided, only playlists containing matching media will be listed.

Switch to the given playlist by making it the active playlist.

Alternative name: change

Create a new playlist. By default, the new playlist is empty, but a flag can be used to start with a copy from an existing playlist.

Options: -p, --playlist   Copy an existing playlist to the new one.

Rename a playlist. By default, this command acts on the active playlist.

Options: -p, --playlist   Rename a different playlist. -f, --force            Force the rename of the collection, overwrite an existing collection if needed.

Remove a playlist. It is disallowed to remove the active playlist.

Configure a playlist by changing its type, attributes, etc.

Options: -p, --playlist   Configure a different playlist. -t, --type       Change the type of the playlist:                        list, queue, pshuffle -i, --input      Set the input collection for the playlist, if needed.                        Useful for pshuffle. (Default: All Media) -s, --history       Size of the history of played tracks. -u, --upcoming      Number of upcoming tracks to keep.

Clear all entries from a playlist. By default, this command acts on the active playlist.

Shuffle a playlist. By default, this command acts on the active playlist.

Sort the entries of a playlist by a list of properties, separated by spaces. By default, this command acts on the active playlist and sorts by a default sequence of properties.

Options: -o, --order <prop1[,prop2...]>  List of properties to sort by                                 (prefix by '-' for reverse ordering).

List all the existing collections.

Display a human-readable description of the collection.

Create a new collection. If a pattern is provided, it is used to define the collection. Otherwise, the new collection contains the whole media library.

Options: -f, --force              Force creation of the collection, overwrite an existing collection if needed. -c, --collection   Copy an existing collection to the new one. -e, --empty              Initialize an empty collection.

Rename a collection.

Options: -f, --force              Force the rename of the collection, overwrite an existing collection if needed.

Remove a collection.

Get or set attributes for the given collection.

If no attribute name or value is provided, list all the attributes. If only an attribute name is provided, display the value of the attribute. If both attribute name and value are provided, set the new value of the attribute.

Import new files into the media library.

By default, directories are imported recursively.

Options: -N, --non-recursive      Do not import directories recursively.

Remove the matching media from the media library.

Note that this operation cannot be undone and recorded properties might get lost!

Rehash (i.e. re-read the metadata) the media matched by the pattern, or the whole media library if no pattern is provided.

Get or set server configuration values.

If no name or value is provided, list all the configuration values. If only a name is provided, display the content of the corresponding configuration value. If both a name and a value are provided, set the new content of the configuration value.

Get or set properties for a given media.

If no name or value is provided, list all the properties. If only a name is provided, display the value of the property. If both a name and a value are provided, set the new value of the property.

By default, set operations use client specific source. List and display operations use source-preference. Use the --source option to override this behaviour.

By default, the value will be used to determine whether it should be saved as a string or an integer. Use the --int or --string flag to override this behaviour.

Options: -i, --int      Force the value to be treated as an integer. -s, --string   Force the value to be treated as a string. -D, --delete   Delete the selected property. -S, --source   Select property source.

List the plugins loaded in the server.

Get or set the audio volume (in a range of 0-100).

If a value is provided, set the new value of the volume. Otherwise, display the current volume.

By default, the command applies to all audio channels. Use the --channel flag to override this behaviour.

Options: -c, --channel   Get or set the volume only for one channel.

Display statistics about the server: uptime, version, size of the medialib, percentage of unindexed media, etc.

Force the saving of collections to the disk (otherwise only performed on shutdown).

Shutdown the server.

A single value represents seconds, but the common hour notation can be used: MM:SS or even HH:MM:SS.

Examples:  42       => 42 seconds  1:11     => 1 minute and 11 seconds  3:25:00  => 3 hours and 25 minutes

An extended version could be implemented, that would recognize strings like 5min, 3.hours, etc.

The pattern syntax would use the xmmsc_coll_parse function and extend it to support additional features, like orderby fields, playlist sequences, pattern references or current position sequences. Many of these could be inspired from the syntax used in nyello, which is described in the code.

Much more extensive description to come here.

The old cli takes some string like "${artist} - ${title}" which assumes that artist and title mediainfo are available. When they are not, the string looks wrong. This also doesn't scale well when additional mediainfo is available, such as the channel in a stream. A new format string specification needs to be drawn up to implement some sort of conditional constructs to allow scalable handling of media.

Basic conditional structure:

%?()()()

The conditional structure takes a simplified condition, which is simply checked to not be an empty string. If the contents of the condition block are not an empty string, the true case is evaluated, otherwise, the false case. Conditional structures should be nestable.

Mediainfo access:

%{}

The mediainfo access structure is simply replaced with a string representation of the property which it represents, or an empty string if the property does not exist.

Thus, the statement:

%?(%{this_property_does_not_exist})(True)(False)

would always print False. While the statement:

%?(this is some text, so this is not an empty string)(True)(False)

would always print True.

Parsing and executing this format is dead simple. The change to % characters is to help command-line interpretation so that the shell does not try to substitute ${}-values. Three special characters should be included as escape sequences, %%, %(, and %).

A good default string for XMMS2 would look like:

%?(%{title})(%?(%{artist})(%{artist} - )()%{title})(%{url})%?(%{channel})( [%{channel}])()

For a little added convenience and to introduce 100 new bugs, shorthand forms could be introduced:

%?()()

by just knocking off the false condition, or even shorter:

%?(<condition/true case>)

by assuming the condition and true case are the same.

Negations (using ^) could be fun in this sense, too:

%?(%{^})()

and could potentially eliminate the need for nesting.