siren.1

.\" Copyright (c) 2011 Tim van der Molen <tim@kariliq.nl>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd May 2, 2019
.Dt SIREN 1
.Os
.Sh NAME
.Nm siren
.Nd text-based audio player
.Sh SYNOPSIS
.Nm siren
.Op Fl lv
.Op Fl c Ar directory
.Sh DESCRIPTION
.Nm
is a text-based audio player.
.Pp
The options are as follows.
.Bl -tag -width Ds
.It Fl c Ar directory
Use
.Ar directory
as the configuration directory.
The default is
.Pa ~/.siren .
.It Fl l
Log error and informational messages to a file.
The file is created in the current directory and named
.Pa siren-%d.log
where
.Pa %d
is replaced with
.Nm Ap s
process ID.
.It Fl v
Print version information and exit.
.El
.Sh USER INTERFACE
.Nm Ap s
user interface consists of three areas.
.Pp
The bottom line is the status line.
It is used to display error and informational messages and to enter commands
and search queries.
.Pp
The two lines above the status line show playback-related information, such as
the currently playing track and the volume level.
.Pp
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
.Ic select-view
command
.Po
see
.Sx COMMANDS
below
.Pc
or the default key bindings.
.Pp
The available views are as follows.
.Bl -tag -width Ds
.It Sy Library view
The library view shows all tracks in the library.
The
.Ic add-path
command may be used to add tracks.
The library view can be displayed by pressing the
.Ic 1
key.
.It Sy Playlist view
The playlist view shows the playlist loaded with the
.Ic load-playlist
command.
It can be displayed by pressing the
.Ic 2
key.
.It Sy 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
.Ic 3
key.
.It Sy 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
.Ic 4
key.
.El
.Pp
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.
.Sh KEY BINDINGS
.Nm
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
.Ic bind-key
and
.Ic unbind-key
commands or shown with the
.Ic show-binding
command.
.Pp
The default key bindings are as follows.
.Bl -tag -width Ds
.It Sy Common key bindings
.Bl -tag -width "^F, page-down" -compact
.It q
Quit
.Nm .
.It x
Play.
.It c
Pause.
.It v
Stop.
.It z
Play the previous track.
.It b
Play the next track.
.It left
Skip backward 5 seconds.
.It ,
Skip backward 1 minute.
.It <
Skip backward 5 minutes.
.It right
Skip forward 5 seconds.
.It .
Skip forward 1 minute.
.It >
Skip forward 5 minutes.
.It -
Decrease the sound volume by 5%.
.It _
Decrease the sound volume by 10%.
.It =
Increase the sound volume by 5%.
.It +
Increase the sound volume by 10%.
.It C
Toggle playback continuation.
.It R
Toggle the repeated playback of all tracks.
.It r
Toggle the repeated playback of the current track.
.It 1
Select the library view.
.It 2
Select the playlist view.
.It 3
Select the browser view.
.It 4
Select the queue view.
.It enter
Activate the selected entry.
.It i
Select the active entry.
.It k, up
Select the previous entry.
.It j, down
Select the next entry.
.It g, home
Select the first entry.
.It G, end
Select the last entry.
.It ^B, page-up
Scroll up one page.
.It ^U
Scroll up half a page.
.It ^Y
Scroll up one line.
.It ^F, page-down
Scroll down one page.
.It ^D
Scroll down half a page.
.It ^E
Scroll down one line.
.It ^L
Refresh the screen.
.It :
Enter the command prompt.
.It /
Enter the search prompt to search forward.
.It ?
Enter the search prompt to search backward.
.It N, p
Search for the previous occurrence.
.It n
Search for the next occurrence.
.It X
Play the active track in the current view, even if that view is not the
playback source.
.It s
Make the current view the playback source.
.El
.It Sy Library view key bindings
.Bl -tag -width "^F, page-down" -compact
.It a
Add the selected entry to the queue.
.It d, delete
Delete the selected entry.
.It l
Delete all entries.
.El
.It Sy Playlist view key bindings
.Bl -tag -width "^F, page-down" -compact
.It a
Add the selected entry to the queue.
.El
.It Sy Browser view key bindings
.Bl -tag -width "^F, page-down" -compact
.It a
Add the selected entry to the queue.
.It h
Toggle the display of hidden files.
.It ^R
Refresh the current directory.
.It backspace
Enter the parent directory.
.El
.It Sy Queue view key bindings
.Bl -tag -width "^F, page-down" -compact
.It J
Move the selected entry downward.
.It K
Move the selected entry upward.
.It d, delete
Delete the selected entry.
.It l
Delete all entries.
.El
.It Sy Prompt key bindings
The key bindings for the prompt currently cannot be changed.
.Pp
.Bl -tag -width "^F, page-down" -compact
.It enter
Process the line and exit the prompt.
.It ^G, escape
Cancel and exit the prompt.
.It ^B, left
Move the cursor to the previous character.
.It ^F, right
Move the cursor to the next character.
.It ^A, home
Move the cursor to the beginning of the line.
.It ^E, end
Move the cursor to the end of the line.
.It ^H, backspace
Delete the character before the cursor.
.It ^D, delete
Delete the character the cursor is at.
.It ^W
Delete the word before the cursor.
.It ^K
Delete all characters from the cursor to the end of the line.
.It ^U
Delete the entire line.
.It down
Replace the line with the previous history entry.
.It up
Replace the line with the next history entry.
.El
.El
.Sh COMMANDS
.Nm
is controlled by issuing commands.
Commands can be entered at the command prompt, bound to a key or added to the
configuration file.
.Pp
Commands are parsed in a way similar to most shells.
A command line is delimited by a newline character or a
.Sq #
character.
A
.Sq #
character introduces a comment and extends to the end of the line.
.Pp
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
.Xr glob 7
pattern expansion is performed.
.Pp
The
.Sq # ,
.Sq ~ ,
.Sq * ,
.Sq \&? ,
.Sq \&[ ,
.Sq \e ,
.Sq \&'
and
.Sq \&"
characters and the space and tab characters are special characters.
A special character can be escaped by prepending it with a
.Sq \e
character or by enclosing it by matching
.Sq \&'
or
.Sq \&"
characters.
.Pp
The following commands are available.
.Bl -tag -width Ds
.It Ic 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.
.It Ic add-entry Op Fl l | q
Add the selected entry to the library or the queue.
The options are as follows.
.Pp
.Bl -tag -width Ds -compact
.It Fl l
Add the selected entry to the library.
This is the default.
.It Fl q
Add the selected entry to the queue.
.El
.It Xo
.Ic add-path
.Op Fl l | q
.Ar path ...
.Xc
Add an audio file or a directory to the library or the queue.
The options are as follows.
.Pp
.Bl -tag -width Ds -compact
.It Fl l
Add
.Ar path
to the library.
.It Fl q
Add
.Ar path
to the queue.
.El
.Pp
The default is to add
.Ar path
to the current view.
If
.Ar path
is a directory, then all audio files in it are added.
.It Ic bind-key Ar scope key command
Bind a key to a command.
.Pp
The
.Ar scope
argument specifies the scope of the key binding.
It should be one of
.Ar browser ,
.Ar library ,
.Ar playlist ,
.Ar queue
or
.Ar common .
.Pp
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
.Ar common
scope.
.Pp
The
.Ar key
argument specifies the key to bind.
The following three types of keys can be bound.
.Bl -dash
.It
The printable ASCII characters: these are the ASCII character codes between 32
and 126 decimal.
They are represented by themselves.
.It
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,
.Ar ^A
and
.Ar ^a
both denote the second control character.
.It
The following case-insensitive key-names are recognised:
.Ar backspace ,
.Ar backtab ,
.Ar delete ,
.Ar down ,
.Ar end ,
.Ar enter ,
.Ar escape ,
.Ar home ,
.Ar insert ,
.Ar left ,
.Ar page-down ,
.Ar page-up ,
.Ar right ,
.Ar space ,
.Ar tab ,
.Ar up
and
.Ar f1
to
.Ar f20 .
.El
.Pp
The
.Ar command
argument can be any command listed in this section.
.It Ic cd Op Ar directory
Change the current working directory to
.Ar directory
and open it in the browser view.
If
.Ar directory
is not specified, the user's home directory is used instead.
.It Ic close-output-plugin
Close the output plug-in.
This may be useful if
.Nm
blocks audio access for other programs.
.It Ic command-prompt
Enter the command prompt.
The command prompt can be used to enter and execute commands.
.It Ic delete-entry Op Fl 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.
.Pp
.Bl -tag -width Ds -compact
.It Fl a
Delete all entries in the current view.
.El
.It Ic load-playlist Ar file
Load the playlist
.Ar file
into the playlist view.
Each line of
.Ar file
should contain the path to a track.
Empty lines and lines starting with the
.Sq #
character are ignored.
.It Ic move-entry-down
Move the selected entry after its succeeding entry.
This command is supported in the queue view only.
.It Ic move-entry-up
Move the entry before its preceding entry.
This command is supported in the queue view only.
.It Ic pause
Pause or resume playback.
.It Ic play
Start, restart or resume playback.
.It Ic play-active
Play the active track in the current view, even if that view is not the
playback source.
.It Ic play-next
Play the next track in the playback source.
.It Ic play-prev
Play the previous track in the playback source.
.It Ic pwd
Print the current working directory.
.It Ic quit
Quit
.Nm .
.It Ic refresh-screen
Refresh the screen.
.It Ic reopen-output-plugin
Reopen the output plug-in.
.It Ic reread-directory
Reread the current directory in the browser view.
.It Ic save-library
Save the library to disk.
The library is automatically saved when
.Nm
quits.
.It Ic save-metadata
Save the metadata cache to disk.
The metadata cache is automatically saved when
.Nm
quits.
.It Xo
.Ic scroll-down
.Op Fl h | l | p
.Xc
Scroll down in the current view.
The options are as follows.
.Pp
.Bl -tag -width Ds -compact
.It Fl h
Scroll half a page.
.It Fl l
Scroll one line.
This is the default.
.It Fl p
Scroll one page.
.El
.It Xo
.Ic scroll-up
.Op Fl h | l | p
.Xc
Scroll up in the current view.
The options are analogous to those of the
.Ic scroll-down
command.
.It Ic search-next
Search for the next occurrence of the text earlier specified with the
.Ic search-prompt
command.
.It Ic search-prev
Search for the previous occurrence of the text earlier specified with the
.Ic search-prompt
command.
.It Ic search-prompt Op Fl b
Enter the search prompt.
The search prompt can be used to search in the current view.
The options are as follows.
.Pp
.Bl -tag -width Ds -compact
.It Fl b
Search backward.
The default is to search forward.
.El
.It Xo
.Ic seek
.Op Fl b | f
.Oo Oo Ar hours Ns Cm \&: Oc Ns Ar minutes Ns Cm \&: Oc Ns Ar seconds
.Xc
Seek to the specified position in the currently playing track.
The options are as follows.
.Pp
.Bl -tag -width Ds -compact
.It Fl b
Seek backward by subtracting the specified position from the current position.
.It Fl f
Seek forward by adding the specified position to the current position.
.El
.It Ic select-active-entry
Select the active entry in the current view.
.It Ic select-first-entry
Select the first entry in the current view.
.It Ic select-last-entry
Select the last entry in the current view.
.It Ic select-next-entry
Select the next entry in the current view.
.It Ic select-prev-entry
Select the previous entry in the current view.
.It Ic select-view Ar name
Select a view.
The
.Ar name
argument must be one of
.Em browser ,
.Em library ,
.Em playlist
or
.Em queue .
.It Ic set Ar option Op Ar value
Set
.Ar option
to
.Ar value .
If
.Ar option
is a Boolean value and
.Ar value
is not specified, it is toggled.
See
.Sx OPTIONS
below for a list of available options.
.It Ic set-playback-source Op Ar source
Set the playback source.
The
.Ar source
argument must be one of
.Em browser ,
.Em library
or
.Em playlist .
If
.Ar source
is not specified, the current view is used, if possible.
.It Xo
.Ic set-volume
.Op Fl d | i
.Ar level
.Xc
Set the volume level.
The
.Ar level
argument should be an integer value between 0 and 100.
The options are as follows.
.Pp
.Bl -tag -width Ds -compact
.It Fl d
Decrease the volume level by
.Ar level .
.It Fl i
Increase the volume level by
.Ar level .
.El
.Pp
Not all output plug-ins have volume support.
.Pp
When using the
.Em oss
output plug-in on
.Fx ,
the volume level may be reset every time a track is played back.
To preserve the volume level, set the
.Em hw.snd.vpc_autoreset
.Xr sysctl 8
variable to 0.
See
.Xr sound 4
for more information.
.It Ic show-binding Ar scope key
Show the command bound to
.Ar key .
The
.Ar scope
and
.Ar key
arguments are analogous to those of the
.Ic bind-key
command.
.It Ic show-option Ar option
Show the value of
.Ar option .
.It Ic source Ar file
Execute the commands in
.Ar file .
.It Ic stop
Stop playback.
.It Ic unbind-key Ar scope key
Unbind
.Ar key .
The
.Ar scope
and
.Ar key
arguments are analogous to those of the
.Ic bind-key
command.
.It Ic update-metadata Op Fl d
Update the metadata cache.
The options are as follows.
.Pp
.Bl -tag -width Ds -compact
.It Fl d
Delete the metadata of tracks that cannot be found on the file system.
.El
.El
.Sh OPTIONS
The appearance and behaviour of
.Nm
may be modified by changing the value of various options.
Options are changed with the
.Ic set
command or shown with the
.Ic show-option
command.
.Pp
There are six types of options.
They are as follows.
.Bl -tag -width Ds
.It Sy Attribute options
Attribute options control the character attributes of a user-interface element.
Valid values are
.Em blink ,
.Em bold ,
.Em dim ,
.Em normal ,
.Em reverse ,
.Em standout
and
.Em underline .
Two or more attributes can be specified by separating them by a comma.
.It Sy Colour options
Colour options control the foreground and background colour of a user-interface
element.
Valid values are
.Em black ,
.Em blue ,
.Em cyan ,
.Em green ,
.Em magenta ,
.Em red ,
.Em white ,
.Em yellow ,
.Em default
and
.Em colour0
to
.Em colourN
where
.Em N
+ 1 is the number of colours supported by the terminal.
.Pp
If supported by the terminal, the colour
.Em default
corresponds to the terminal's original background or foreground colour.
Otherwise,
.Em default
is equivalent to
.Em black
when used as a background colour and to
.Em white
when used as a foreground colour.
.It Sy Boolean options
Valid values of Boolean options are
.Em true
and
.Em false .
As a convenience, the values
.Em on ,
.Em off ,
.Em yes ,
.Em no ,
.Em 1
and
.Em 0
are accepted as well.
.It Sy Number options
Valid values of number options are non-negative integers.
The maximum value is option-specific.
.It Sy String options
Valid values of string options are option-specific.
.It Sy Format-string options
Format-string options control the formatting of information displayed on the
screen.
The syntax is reminiscent of that of the
.Xr printf 3
family of functions.
.Pp
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
.Sq %
character.
Then, the following appears in sequence.
.Bl -dash
.It
An optional
.Sq -
character to specify that the variable is to be left-aligned within the field.
The default is to right-align.
.It
An optional
.Sq 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.
.It
An optional sequence of numeric characters to specify the field width.
If the
.Sq *
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.
.It
The name of the variable to display, enclosed by braces
.Po
i.e. the
.Sq {
and
.Sq }
characters
.Pc .
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.
.Pp
Conditional fields are also supported.
A conditional field is enclosed in braces and begins with a
.Sq \&?
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,
.Sq %{?artist,yes,no}
displays
.Sq yes
if
.Em artist
is a non-empty string and
.Sq no
otherwise.
.El
.Pp
A literal
.Sq %
character is displayed by specifying
.Sq %%
in the format string.
.El
.Pp
The following options are available.
.Bl -tag -width Ds
.It Cm active-attr Pq attribute
Character attributes for the activated menu entry.
The default is
.Em normal .
.It Cm active-bg Pq colour
Background colour for the activated menu entry.
The default is
.Em default .
.It Cm active-fg Pq colour
Foreground colour for the activated menu entry.
The default is
.Em yellow .
.It Cm continue Pq Boolean
Whether to play the next track if the current track has finished.
The default is
.Em true .
.It Cm continue-after-error Pq Boolean
Whether to play the next track if playback of the current track was stopped due
to an error.
The default is
.Em false .
.It Cm error-attr Pq attribute
Character attributes for error messages.
The default is
.Em normal .
.It Cm error-bg Pq colour
Background colour for error messages.
The default is
.Em default .
.It Cm error-fg Pq colour
Foreground colour for error messages.
The default is
.Em red .
.It Cm info-attr Pq attribute
Character attributes for informational messages.
The default is
.Em normal .
.It Cm info-bg Pq colour
Background colour for informational messages.
The default is
.Em default .
.It Cm info-fg Pq colour
Foreground colour for informational messages.
The default is
.Em cyan .
.It Cm library-format Pq format string
The format used to display tracks in the library.
The following variables are available.
.Bl -column tracknumber alias
.It Sy Name Ta Sy Alias Ta Sy Description
.It album Ta l Ta Album
.It albumartist Ta A Ta Album artist
.It artist Ta a Ta Artist
.It comment Ta c Ta Comment
.It date Ta y Ta Date or year
.It discnumber Ta s Ta Disc number
.It disctotal Ta S Ta Total number of discs
.It duration Ta d Ta Duration Pq as So m:ss Sc or So h:mm:ss Sc
.It filename Ta F Ta Filename
.It genre Ta g Ta Genre
.It path Ta f Ta File path
.It title Ta t Ta Title
.It tracknumber Ta n Ta Track number
.It tracktotal Ta N Ta Total number of tracks
.El
.Pp
The default is
.Sq %-*a %-*l %4y %2n. %-*t %5d .
.It Cm library-format-alt Pq format string
The alternative format used to display tracks in the library that have a
missing or empty
.Em title
metadata field.
See the
.Cm library-format
option for a list of available variables.
If this option is empty, the
.Cm library-format
option is used.
The default is
.Sq %-*F %5d .
.It Cm output-plugin Pq string
The name of the output plug-in to use.
If the special name
.Ar default
is specified, the output plug-in with the highest priority will be used.
.Pp
The following output plug-ins may be available, depending on the compile-time
options used.
They are listed in descending order of priority.
.Pp
.Bl -tag -width portaudio -compact
.It sndio
.Ox
.Xr sndio 7
output plug-in
.It pulse
PulseAudio output plug-in
.It sun
Sun output plug-in
.It alsa
ALSA output plug-in
.It oss
OSS output plug-in
.It ao
libao output plug-in
.It portaudio
PortAudio output plug-in
.El
.Pp
The default is
.Sq default .
.It Cm player-attr Pq attribute
Character attributes for the player area.
The default is
.Em reverse .
.It Cm player-bg Pq colour
Background colour for the player area.
The default is
.Em default .
.It Cm player-fg Pq colour
Foreground colour of the player area.
The default is
.Em default .
.It Cm player-status-format Pq format string
The format used to display the player status.
The following variables are available.
.Bl -column repeat-track alias
.It Sy Name Ta Sy Alias Ta Sy Description
.It continue Ta c Ta
Expands to
.Sq continue
or the empty string, depending on the value of the
.Cm continue
option
.It duration Ta d Ta
Duration of the currently playing track
.Pq as So m:ss Sc or So h:mm:ss Sc
.It position Ta p Ta
Position in the currently playing track
.Pq as So m:ss Sc or So h:mm:ss Sc
.It repeat-all Ta r Ta
Expands to
.Sq repeat-all
or the empty string, depending on the value of the
.Cm repeat-all
option
.It repeat-track Ta t Ta
Expands to
.Sq repeat-track
or the empty string, depending on the value of the
.Cm repeat-track
option
.It source Ta u Ta
Playback source
.It state Ta s Ta
Expands to
.Sq Playing ,
.Sq Paused
or
.Sq Stopped ,
depending on the playback state
.It volume Ta v Ta Sound volume
.El
.Pp
The default is:
.Bd -literal -offset indent
%-7s  %5p / %5d  %3v%%  %u%{?c,  continue,}%{?r,  repeat-all,}%{?t,  repeat-track,}
.Ed
.It Cm player-track-format Pq format string
The format used to display the currently playing track.
See the
.Cm library-format
option for a list of available variables.
The default is
.Sq %a - %l (%y) - %n. %t .
.It Cm player-track-format-alt Pq format string
The alternative format used to display the currently playing track if it has a
missing or empty
.Em title
metadata field.
See the
.Cm library-format
option for a list of available variables.
If this option is empty, the
.Cm player-track-format
option is used.
The default is
.Sq %F .
.It Cm playlist-format Pq format string
The format used to display tracks in the playlist view.
See the
.Cm library-format
option for a list of available variables.
The default is
.Sq %-*a %-*t %5d .
.It Cm playlist-format-alt Pq format string
The alternative format used to display tracks in the playlist that have a
missing or empty
.Em title
metadata field.
See the
.Cm library-format
option for a list of available variables.
If this option is empty, the
.Cm playlist-format
option is used.
The default is
.Sq %-*F %5d .
.It Cm prompt-attr Pq attribute
Character attributes for the prompt.
The default is
.Em normal .
.It Cm prompt-bg Pq colour
Background colour for the prompt.
The default is
.Em default .
.It Cm prompt-fg Pq colour
Foreground colour for the prompt.
The default is
.Em default .
.It Cm queue-format Pq format string
The format used to display tracks in the queue.
See the
.Cm library-format
option for a list of available variables.
The default is
.Sq %-*a %-*t %5d .
.It Cm queue-format-alt Pq format string
The alternative format used to display tracks in the queue that have a
missing or empty
.Em title
metadata field.
See the
.Cm library-format
option for a list of available variables.
If this option is empty, the
.Cm queue-format
option is used.
The default is
.Sq %-*F %5d .
.It Cm repeat-all Pq Boolean
Whether to repeat playback of all tracks in the playback source.
The default is
.Em true .
.It Cm repeat-track Pq Boolean
Whether to repeat playback of the current track.
This option takes precedence over the
.Cm repeat-all
option.
The default is
.Em false .
.It Cm selection-attr Pq attribute
Character attributes for the selection indicator.
The default is
.Em reverse .
.It Cm selection-bg Pq colour
Background colour for the selection indicator.
The default is
.Em white .
.It Cm selection-fg Pq colour
Foreground colour for the selection indicator.
The default is
.Em blue .
.It Cm show-all-files Pq Boolean
Whether to show all files in the browser view.
If set to
.Em false ,
only directories and supported audio files are shown.
The default is
.Em false .
.It Cm show-cursor Pq Boolean
Whether always to show the cursor.
The default is
.Em false .
.It Cm show-hidden-files Pq Boolean
Whether to show hidden files and directories in the browser view.
The default is
.Em false .
.It Cm status-attr Pq attribute
Character attributes for the status line.
The default is
.Em normal .
.It Cm status-bg Pq colour
Background colour for the status line.
The default is
.Em default .
.It Cm status-fg Pq colour
Foreground colour for the status line.
The default is
.Em default .
.It Cm view-attr Pq attribute
Character attributes for the view.
The default is
.Em normal .
.It Cm view-bg Pq colour
Background colour for the view.
The default is
.Em default .
.It Cm view-fg Pq colour
Foreground colour for the view.
The default is
.Em default .
.It Cm view-title-attr Pq attribute
Character attributes for the view title.
The default is
.Em reverse .
.It Cm view-title-bg Pq colour
Background colour for the view title.
The default is
.Em default .
.It Cm view-title-fg Pq colour
Foreground colour for the view title.
The default is
.Em default .
.El
.Pp
The following options are specific to the
.Em alsa
output plug-in.
.Bl -tag -width Ds
.It Cm alsa-mixer-device Pq string
The name of the mixer device to use.
The default is
.Sq default .
.It Cm alsa-mixer-element Pq string
The name of the mixer element to use.
The default is
.Sq PCM .
.It Cm alsa-pcm-device Pq string
The name of the PCM device to use.
The default is
.Sq default .
.El
.Pp
The following options are specific to the
.Em ao
output plug-in.
.Bl -tag -width Ds
.It Cm ao-buffer-size Pq number
The size of the output buffer, specified in bytes.
The default is 4096.
.It Cm ao-driver Pq string
The name of the driver to use.
If empty, the default driver will be used.
See
.Xr libao.conf 5
and
.Lk https://www.xiph.org/ao/doc/drivers.html
for possible values.
The default is empty.
.El
.Pp
The following options are specific to the
.Em oss
output plug-in.
.Bl -tag -width Ds
.It Cm oss-device Pq string
The path of the audio device to use.
The default is
.Sq /dev/dsp .
.El
.Pp
The following options are specific to the
.Em portaudio
output plug-in.
.Bl -tag -width Ds
.It Cm portaudio-buffer-size Pq number
The size of the output buffer, specified in bytes.
The default is 4096.
.El
.Pp
The following options are specific to the
.Em pulse
output plug-in.
.Bl -tag -width Ds
.It Cm pulse-buffer-size Pq number
The size of the output buffer, specified in bytes.
The default is 4096.
.El
.Pp
The following options are specific to the
.Em sndio
output plug-in.
.Bl -tag -width Ds
.It Cm sndio-device Pq string
The name of the device to use.
See
.Xr sndio 7
for possible values.
The default is
.Sq default .
.El
.Pp
The following options are specific to the
.Em sun
output plug-in.
.Bl -tag -width Ds
.It Cm sun-device Pq string
The path of the audio device to use.
The default is
.Sq /dev/audio .
.El
.Sh CONFIGURATION FILE
Upon start-up
.Nm
reads the configuration file
.Pa ~/.siren/config ,
if it exists.
This file should contain a set of
.Nm
commands
.Pq see Sx COMMANDS
which are executed in sequence.
.Sh FILES
.Bl -tag -width ~/.siren/metadata -compact
.It Pa ~/.siren/config
Configuration file.
.It Pa ~/.siren/library
Library file.
.It Pa ~/.siren/metadata
Metadata cache file.
.El
.Sh SEE ALSO
.Xr pulseaudio 1 ,
.Xr sound 4 ,
.Xr libao.conf 5 ,
.Xr sndio 7
.Pp
.Lk https://www.kariliq.nl/siren/
.Sh AUTHORS
.An Tim van der Molen Aq Mt tim@kariliq.nl