NAME

siren —

text-based audio player

SYNOPSIS

siren [-lv] [-c directory]

DESCRIPTION

siren is a text-based audio player.

The options are as follows.

-c directory: Use directory as the configuration directory. The default is ~/.siren.
-l: Log error and informational messages to a file. The file is created in the current directory and named siren-%d.log where %d is replaced with siren's process ID.
-v: Print version information and exit.

USER INTERFACE

siren's user interface consists of three areas.

The bottom line is the status line. It is used to display error and informational messages and to enter commands and search queries.

The two lines above the status line show playback-related information, such as the currently playing track and the volume level.

The remainder of the screen is used to display a view. Only one view can be displayed at a time, but each view can be selected with the select-view command (see COMMANDS below) or the default key bindings.

The available views are as follows.

Library view: The library view shows all tracks in the library. The add-path command may be used to add tracks. The library view can be displayed by pressing the 1 key.
Playlist view: The playlist view shows the playlist loaded with the load-playlist command. It can be displayed by pressing the 2 key.
Browser view: The browser view shows the contents of a directory. By default only directories and supported audio files are shown. The browser view can be used to browse through the file system and play back audio files or add them to the library or queue. The browser view can be displayed by pressing the 3 key.
Queue view: The queue view shows all tracks that have been added to the queue. Tracks in the queue will be played back before those in other views. A track will be removed from the queue as soon as it is being played back. The queue view can be displayed by pressing the 4 key.

The playback source is the view that provides the tracks for playback. The library, playlist and browser views each can act as a playback source. A view implicitly becomes the playback source whenever a track from that view is selected for playback.

KEY BINDINGS

siren supports configurable key bindings. Each key binding has a scope: it is either specific to one view or common to all views. Key bindings are changed with the bind-key and unbind-key commands or shown with the show-binding command.

The default key bindings are as follows.

Common key bindings

q: Quit siren.
x: Play.
c: Pause.
v: Stop.
z: Play the previous track.
b: Play the next track.
left: Skip backward 5 seconds.
,: Skip backward 1 minute.
<: Skip backward 5 minutes.
right: Skip forward 5 seconds.
.: Skip forward 1 minute.
>: Skip forward 5 minutes.
-: Decrease the sound volume by 5%.
_: Decrease the sound volume by 10%.
=: Increase the sound volume by 5%.
+: Increase the sound volume by 10%.
C: Toggle playback continuation.
R: Toggle the repeated playback of all tracks.
r: Toggle the repeated playback of the current track.
1: Select the library view.
2: Select the playlist view.
3: Select the browser view.
4: Select the queue view.
enter: Activate the selected entry.
i: Select the active entry.
k, up: Select the previous entry.
j, down: Select the next entry.
g, home: Select the first entry.
G, end: Select the last entry.
^B, page-up: Scroll up one page.
^U: Scroll up half a page.
^Y: Scroll up one line.
^F, page-down: Scroll down one page.
^D: Scroll down half a page.
^E: Scroll down one line.
^L: Refresh the screen.
:: Enter the command prompt.
/: Enter the search prompt to search forward.
?: Enter the search prompt to search backward.
N, p: Search for the previous occurrence.
n: Search for the next occurrence.

Library view key bindings

a: Add the selected entry to the queue.
d, delete: Delete the selected entry.
l: Delete all entries.

Playlist view key bindings

a: Add the selected entry to the queue.

Browser view key bindings

a: Add the selected entry to the queue.
h: Toggle the display of hidden files.
^R: Refresh the current directory.
backspace: Enter the parent directory.

Queue view key bindings

J: Move the selected entry downward.
K: Move the selected entry upward.
d, delete: Delete the selected entry.
l: Delete all entries.

Prompt key bindings

The key bindings for the prompt currently cannot be changed.

enter: Process the line and exit the prompt.
^G, escape: Cancel and exit the prompt.
^B, left: Move the cursor to the previous character.
^F, right: Move the cursor to the next character.
^A, home: Move the cursor to the beginning of the line.
^E, end: Move the cursor to the end of the line.
^H, backspace: Delete the character before the cursor.
^D, delete: Delete the character the cursor is at.
^W: Delete the word before the cursor.
^K: Delete all characters from the cursor to the end of the line.
^U: Delete the entire line.
down: Replace the line with the previous history entry.
up: Replace the line with the next history entry.

COMMANDS

siren is controlled by issuing commands. Commands can be entered at the command prompt, bound to a key or added to the configuration file.

Commands are parsed in a way similar to most shells. A command line is delimited by a newline character or a ‘#’ character. A ‘#’ character introduces a comment and extends to the end of the line.

A command line is broken into separate words. A word is a sequence of characters and is delimited by one or more space or tab characters. On each word, tilde expansion and glob(3) pattern expansion is performed.

The ‘#’, ‘~’, ‘*’, ‘?’, ‘[’, ‘\’, ‘'’ and ‘"’ characters and the space and tab characters are special characters. A special character can be escaped by prepending it with a ‘\’ character or by enclosing it by matching ‘'’ or ‘"’ characters.

The following commands are available.

activate-entry

Activate the selected entry in the current view. In the library and playlist views, an activated entry is played back. In the browser view, if the activated entry is a directory, it is entered. Otherwise, if it is a file, it is played back. In the queue view, an activated entry is played back and removed from the queue.

add-entry [-l | -q]

Add the selected entry to the library or the queue. The options are as follows.

-l: Add the selected entry to the library. This is the default.
-q: Add the selected entry to the queue.

add-path [-l | -q] path ...

Add an audio file or a directory to the library or the queue. The options are as follows.

-l: Add path to the library.
-q: Add path to the queue.

The default is to add path to the current view. If path is a directory, then all audio files in it are added.

bind-key scope key command

Bind a key to a command.

The scope argument specifies the scope of the key binding. It should be one of browser, library, playlist, queue or common.

A key binding is first looked up in the scope of the current view. If no key binding is found in that scope, then it is looked up in the common scope.

The key argument specifies the key to bind. The following three types of keys can be bound.

The printable ASCII characters: these are the ASCII character codes between 32 and 126 decimal. They are represented by themselves.
The ASCII control characters: these are the ASCII character codes between 0 and 31 decimal. They are specified in case-insensitive caret notation. For example, ^A and ^a both denote the second control character.
The following case-insensitive key-names are recognised: backspace, backtab, delete, down, end, enter, escape, home, insert, left, page-down, page-up, right, space, tab, up and f1 to f20.

The command argument can be any command listed in this section.

cd [directory]

Change the current working directory to directory and open it in the browser view. If directory is not specified, the user's home directory is used instead.

close-output-plugin

Close the output plug-in. This may be useful if siren blocks audio access for other programs.

command-prompt

Enter the command prompt. The command prompt can be used to enter and execute commands.

delete-entry [-a]

Delete the selected entry in the current view. This command is supported in the library and queue views only. The options are as follows.

-a: Delete all entries in the current view.

load-playlist file

Load the playlist file into the playlist view. Each line of file should contain the path to a track. Empty lines and lines starting with the ‘#’ character are ignored.

move-entry-down

Move the selected entry after its succeeding entry. This command is supported in the queue view only.

move-entry-up

Move the entry before its preceding entry. This command is supported in the queue view only.

pause

Pause or resume playback.

play

Start, restart or resume playback.

play-next

Play the next track in the playback source.

play-prev

Play the previous track in the playback source.

pwd

Print the current working directory.

quit

Quit siren.

refresh-screen

Refresh the screen.

reopen-output-plugin

Reopen the output plug-in.

reread-directory

Reread the current directory in the browser view.

save-library

Save the library to disk. The library is automatically saved when siren quits.

save-metadata

Save the metadata cache to disk. The metadata cache is automatically saved when siren quits.

scroll-down [-h | -l | -p]

Scroll down in the current view. The options are as follows.

-h: Scroll half a page.
-l: Scroll one line. This is the default.
-p: Scroll one page.

scroll-up [-h | -l | -p]

Scroll up in the current view. The options are analogous to those of the scroll-down command.

search-next

Search for the next occurrence of the text earlier specified with the search-prompt command.

search-prev

Search for the previous occurrence of the text earlier specified with the search-prompt command.

search-prompt [-b]

Enter the search prompt. The search prompt can be used to search in the current view. The options are as follows.

-b: Search backward. The default is to search forward.

seek [-b | -f] [[hours:]minutes:]seconds

Seek to the specified position in the currently playing track. The options are as follows.

-b: Seek backward by subtracting the specified position from the current position.
-f: Seek forward by adding the specified position to the current position.

select-active-entry

Select the active entry in the current view.

select-first-entry

Select the first entry in the current view.

select-last-entry

Select the last entry in the current view.

select-next-entry

Select the next entry in the current view.

select-prev-entry

Select the previous entry in the current view.

select-view name

Select a view. The name argument must be one of browser, library, playlist or queue.

set option [value]

Set option to value. If option is a Boolean value and value is not specified, it is toggled. See OPTIONS below for a list of available options.

set-volume [-d | -i] level

Set the volume level. The level argument should be an integer value between 0 and 100. The options are as follows.

-d: Decrease the volume level by level.
-i: Increase the volume level by level.

Not all output plug-ins have volume support.

When using the oss output plug-in on FreeBSD, the volume level may be reset every time a track is played back. To preserve the volume level, set the hw.snd.vpc_autoreset sysctl(8) variable to 0. See sound(4) for more information.

show-binding scope key

Show the command bound to key. The scope and key arguments are analogous to those of the bind-key command.

show-option option

Show the value of option.

source file

Execute the commands in file.

stop

Stop playback.

unbind-key scope key

Unbind key. The scope and key arguments are analogous to those of the bind-key command.

update-metadata [-d]

Update the metadata cache. The options are as follows.

-d: Delete the metadata of tracks that cannot be found on the file system.

OPTIONS

The appearance and behaviour of siren may be modified by changing the value of various options. Options are changed with the set command or shown with the show-option command.

There are six types of options. They are as follows.

Attribute options

Attribute options control the character attributes of a user-interface element. Valid values are blink, bold, dim, normal, reverse, standout and underline. Two or more attributes can be specified by separating them by a comma.

Colour options

Colour options control the foreground and background colour of a user-interface element. Valid values are black, blue, cyan, green, magenta, red, white, yellow, default and colour0 to colourN where N + 1 is the number of colours supported by the terminal.

If supported by the terminal, the colour default corresponds to the terminal's original background or foreground colour. Otherwise, default is equivalent to black when used as a background colour and to white when used as a foreground colour.

Boolean options

Valid values of Boolean options are true and false. As a convenience, the values on, off, yes, no, 1 and 0 are accepted as well.

Number options

Valid values of number options are non-negative integers. The maximum value is option-specific.

String options

Valid values of string options are option-specific.

Format-string options

Format-string options control the formatting of information displayed on the screen. The syntax is reminiscent of that of the printf(3) family of functions.

A format string consists of ordinary characters, which are displayed unchanged, and format fields, which specify how a variable is to be displayed. A format field is introduced by the ‘%’ character. Then, the following appears in sequence.

An optional ‘-’ character to specify that the variable is to be left-aligned within the field. The default is to right-align.
An optional ‘0’ character to specify that the variable is to be padded with leading zeroes. The default is to pad with space characters. This flag is ignored if the variable is to be left-aligned.
An optional sequence of numeric characters to specify the field width. If the ‘*’ character is specified, the width is variable and will be so long as possible. If there are two or more fields with a variable width, the available space will be divided equally between them.
The name of the variable to display, enclosed by braces (i.e. the ‘{’ and ‘}’ characters). Some variables also have a one-character alias. If this alias is specified, the braces may be omitted. Which variables are available is dependent on the option.
Conditional fields are also supported. A conditional field is enclosed in braces and begins with a ‘?’ character, followed by the name of the variable and two comma-separated fields. If the variable is a non-zero number or a non-empty string, the first value is displayed; otherwise, the second value. For example, ‘%{?artist,yes,no}’ displays ‘yes’ if artist is a non-empty string and ‘no’ otherwise.

A literal ‘%’ character is displayed by specifying ‘%%’ in the format string.

The following options are available.

active-attr (attribute)

Character attributes for the activated menu entry. The default is normal.

active-bg (colour)

Background colour for the activated menu entry. The default is default.

active-fg (colour)

Foreground colour for the activated menu entry. The default is yellow.

continue (Boolean)

Whether to play the next track if the current track has finished. The default is true.

continue-after-error (Boolean)

Whether to play the next track if playback of the current track was stopped due to an error. The default is false.

error-attr (attribute)

Character attributes for error messages. The default is normal.

error-bg (colour)

Background colour for error messages. The default is default.

error-fg (colour)

Foreground colour for error messages. The default is red.

info-attr (attribute)

Character attributes for informational messages. The default is normal.

info-bg (colour)

Background colour for informational messages. The default is default.

info-fg (colour)

Foreground colour for informational messages. The default is cyan.

library-format (format string)

The format used to display tracks in the library. The following variables are available.

Name	Alias	Description
album	l	Album
albumartist	A	Album artist
artist	a	Artist
comment	c	Comment
date	y	Date or year
discnumber	s	Disc number
disctotal	S	Total number of discs
duration	d	Duration (as ‘m:ss’ or ‘h:mm:ss’)
filename	F	Filename
genre	g	Genre
path	f	File path
title	t	Title
tracknumber	n	Track number
tracktotal	N	Total number of tracks

The default is ‘%-*a %-*l %4y %2n. %-*t %5d’.

library-format-alt (format string)

The alternative format used to display tracks in the library that have a missing or empty title metadata field. See the library-format option for a list of available variables. If this option is empty, the library-format option is used. The default is ‘%-*F %5d’.

output-plugin (string)

The name of the output plug-in to use. If the special name default is specified, the output plug-in with the highest priority will be used.

The following output plug-ins may be available, depending on the compile-time options used. They are listed in descending order of priority.

sndio: OpenBSD sndio(7) output plug-in
pulse: PulseAudio output plug-in
sun: Sun output plug-in
alsa: ALSA output plug-in
oss: OSS output plug-in
ao: libao output plug-in
portaudio: PortAudio output plug-in

The default is ‘default’.

player-attr (attribute)

Character attributes for the player area. The default is reverse.

player-bg (colour)

Background colour for the player area. The default is default.

player-fg (colour)

Foreground colour of the player area. The default is default.

player-status-format (format string)

The format used to display the player status. The following variables are available.

Name	Alias	Description
continue	c	Expands to ‘continue’ or the empty string, depending on the value of the `continue` option
duration	d	Duration of the currently playing track (as ‘m:ss’ or ‘h:mm:ss’)
position	p	Position in the currently playing track (as ‘m:ss’ or ‘h:mm:ss’)
repeat-all	r	Expands to ‘repeat-all’ or the empty string, depending on the value of the `repeat-all` option
repeat-track	t	Expands to ‘repeat-track’ or the empty string, depending on the value of the `repeat-track` option
source	u	Playback source
state	s	Expands to ‘Playing’, ‘Paused’ or ‘Stopped’, depending on the playback state
volume	v	Sound volume

The default is:

%-7s  %5p / %5d  %3v%%  %u%{?c,  continue,}%{?r,  repeat-all,} %{?t,  repeat-track,}

player-track-format (format string)

The format used to display the currently playing track. See the library-format option for a list of available variables. The default is ‘%a - %l (%y) - %n. %t’.

player-track-format-alt (format string)

The alternative format used to display the currently playing track if it has a missing or empty title metadata field. See the library-format option for a list of available variables. If this option is empty, the player-track-format option is used. The default is ‘%F’.

playlist-format (format string)

The format used to display tracks in the playlist view. See the library-format option for a list of available variables. The default is ‘%-*a %-*t %5d’.

playlist-format-alt (format string)

The alternative format used to display tracks in the playlist that have a missing or empty title metadata field. See the library-format option for a list of available variables. If this option is empty, the playlist-format option is used. The default is ‘%-*F %5d’.

prompt-attr (attribute)

Character attributes for the prompt. The default is normal.

prompt-bg (colour)

Background colour for the prompt. The default is default.

prompt-fg (colour)

Foreground colour for the prompt. The default is default.

queue-format (format string)

The format used to display tracks in the queue. See the library-format option for a list of available variables. The default is ‘%-*a %-*t %5d’.

queue-format-alt (format string)

The alternative format used to display tracks in the queue that have a missing or empty title metadata field. See the library-format option for a list of available variables. If this option is empty, the queue-format option is used. The default is ‘%-*F %5d’.

repeat-all (Boolean)

Whether to repeat playback of all tracks in the playback source. The default is true.

repeat-track (Boolean)

Whether to repeat playback of the current track. This option takes precedence over the repeat-all option. The default is false.

selection-attr (attribute)

Character attributes for the selection indicator. The default is reverse.

selection-bg (colour)

Background colour for the selection indicator. The default is white.

selection-fg (colour)

Foreground colour for the selection indicator. The default is blue.

show-all-files (Boolean)

Whether to show all files in the browser view. If set to false, only directories and supported audio files are shown. The default is false.

show-cursor (Boolean)

Whether always to show the cursor. The default is false.

show-hidden-files (Boolean)

Whether to show hidden files and directories in the browser view. The default is false.

status-attr (attribute)

Character attributes for the status line. The default is normal.

status-bg (colour)

Background colour for the status line. The default is default.

status-fg (colour)

Foreground colour for the status line. The default is default.

view-attr (attribute)

Character attributes for the view. The default is normal.

view-bg (colour)

Background colour for the view. The default is default.

view-fg (colour)

Foreground colour for the view. The default is default.

view-title-attr (attribute)

Character attributes for the view title. The default is reverse.

view-title-bg (colour)

Background colour for the view title. The default is default.

view-title-fg (colour)

Foreground colour for the view title. The default is default.

The following options are specific to the alsa output plug-in.

alsa-mixer-device (string): The name of the mixer device to use. The default is ‘default’.
alsa-mixer-element (string): The name of the mixer element to use. The default is ‘PCM’.
alsa-pcm-device (string): The name of the PCM device to use. The default is ‘default’.

The following options are specific to the ao output plug-in.

ao-buffer-size (number): The size of the output buffer, specified in bytes. The default is 4096.
ao-driver (string): The name of the driver to use. If empty, the default driver will be used. See libao.conf(5) and https://www.xiph.org/ao/doc/drivers.html for possible values. The default is empty.

The following options are specific to the oss output plug-in.

oss-device (string): The path of the audio device to use. The default is ‘/dev/dsp’.

The following options are specific to the portaudio output plug-in.

portaudio-buffer-size (number): The size of the output buffer, specified in bytes. The default is 4096.

The following options are specific to the pulse output plug-in.

pulse-buffer-size (number): The size of the output buffer, specified in bytes. The default is 4096.

The following options are specific to the sndio output plug-in.

sndio-device (string): The name of the device to use. See sndio(7) for possible values. The default is ‘default’.

The following options are specific to the sun output plug-in.

sun-device (string): The path of the audio device to use. The default is ‘/dev/audio’.

CONFIGURATION FILE

Upon start-up siren reads the configuration file ~/.siren/config, if it exists. This file should contain a set of siren commands (see COMMANDS) which are executed in sequence.

FILES

~/.siren/config: Configuration file.
~/.siren/library: Library file.
~/.siren/metadata: Metadata cache file.

AUTHORS

Tim van der Molen <tim@kariliq.nl>