2015-01-07 17:44:44 -05:00
|
|
|
.\" Copyright (c) 2007, 2009, 2015 Moritz Grimm <mgrimm@mrsserver.net>
|
2009-08-30 15:38:48 -04:00
|
|
|
.\"
|
|
|
|
.\" This program is free software; you can redistribute it and/or modify
|
|
|
|
.\" it under the terms of the GNU General Public License version 2 as
|
|
|
|
.\" published by the Free Software Foundation.
|
|
|
|
.\"
|
|
|
|
.\" This program is distributed in the hope that it will be useful,
|
|
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
|
.\" GNU General Public License for more details.
|
|
|
|
.\"
|
2009-08-30 08:49:06 -04:00
|
|
|
.Dd @BUILD_DATE@
|
2007-02-24 15:52:57 -05:00
|
|
|
.Dt EZSTREAM 1
|
2009-08-30 08:49:06 -04:00
|
|
|
.Os @PACKAGE_NAME@ @PACKAGE_VERSION@
|
2007-02-24 15:52:57 -05:00
|
|
|
.Sh NAME
|
|
|
|
.Nm ezstream
|
2007-03-08 21:30:29 -05:00
|
|
|
.Nd source client for Icecast with external de-/encoder support
|
2007-02-24 15:52:57 -05:00
|
|
|
.Sh SYNOPSIS
|
|
|
|
.Nm
|
|
|
|
.Bk -words
|
2015-05-14 17:29:38 -04:00
|
|
|
.Op Fl hqrVv
|
2007-08-22 11:19:17 -04:00
|
|
|
.Fl c Ar configfile
|
2007-02-24 15:52:57 -05:00
|
|
|
.Ek
|
2009-08-30 17:55:24 -04:00
|
|
|
.Nm
|
|
|
|
.Bk -words
|
2015-05-14 17:29:38 -04:00
|
|
|
.Fl s Ar file
|
2009-08-30 17:55:24 -04:00
|
|
|
.Ek
|
2007-02-24 15:52:57 -05:00
|
|
|
.Sh DESCRIPTION
|
|
|
|
The
|
|
|
|
.Nm
|
|
|
|
utility is a source client for the Icecast media streaming server.
|
|
|
|
In its basic mode of operation, it streams media files and data from standard
|
|
|
|
input
|
|
|
|
.Qq as-is
|
|
|
|
\(em such as Ogg Vorbis, Ogg Theora and MP3 \(em to a server.
|
2007-07-13 06:30:58 -04:00
|
|
|
It can also use various external decoders and encoders to re-encode from one
|
2007-02-24 15:52:57 -05:00
|
|
|
format to another, and stream the result.
|
|
|
|
The only requirement is that the external programs support writing to or
|
|
|
|
reading from standard input, and can be used from the command line.
|
2015-05-14 17:29:38 -04:00
|
|
|
.Ss Command line arguments
|
2007-02-24 15:52:57 -05:00
|
|
|
.Bl -tag -width Ds
|
|
|
|
.It Fl c Ar configfile
|
|
|
|
Use the XML configuration in
|
|
|
|
.Ar configfile .
|
|
|
|
.It Fl h
|
2015-05-14 17:29:38 -04:00
|
|
|
Print a summary of available command line arguments with short descriptions
|
2007-02-24 15:52:57 -05:00
|
|
|
and exit.
|
|
|
|
.It Fl q
|
|
|
|
Be more quiet.
|
|
|
|
Suppress the output that external programs send to standard error.
|
2015-05-14 17:29:38 -04:00
|
|
|
.It Fl r
|
|
|
|
Maintain a line of real-time status information about the stream on standard
|
|
|
|
output.
|
|
|
|
.Po
|
|
|
|
Implies
|
|
|
|
.Fl q .
|
|
|
|
.Pc
|
|
|
|
.It Fl s Ar file
|
2009-08-30 17:55:24 -04:00
|
|
|
Run
|
|
|
|
.Nm
|
|
|
|
as a line-based shuffling utility.
|
2015-04-15 18:08:43 -04:00
|
|
|
If a
|
2009-08-30 17:55:24 -04:00
|
|
|
.Ar playlist
|
2015-04-15 18:08:43 -04:00
|
|
|
argument of
|
|
|
|
.Dq -
|
|
|
|
is given, a list of media file names is read from standard input
|
2009-08-30 17:55:24 -04:00
|
|
|
instead of an input file.
|
|
|
|
After successfully reading the entire list, it is shuffled and printed to
|
|
|
|
standard output, and
|
|
|
|
.Nm
|
|
|
|
will exit.
|
2007-03-04 09:27:37 -05:00
|
|
|
.It Fl V
|
|
|
|
Print the
|
|
|
|
.Nm
|
|
|
|
version number and exit.
|
2007-02-24 15:52:57 -05:00
|
|
|
.It Fl v
|
2015-05-14 17:29:38 -04:00
|
|
|
Increase logging verbosity.
|
|
|
|
May be used up to three times to also include debug logging output.
|
2007-02-24 15:52:57 -05:00
|
|
|
.El
|
|
|
|
.Ss Runtime control
|
|
|
|
On POSIX systems,
|
|
|
|
.Nm
|
2007-03-08 21:30:29 -05:00
|
|
|
offers limited runtime control via signals.
|
2007-02-24 15:52:57 -05:00
|
|
|
By sending a signal to the ezstream process, e.g. with the
|
|
|
|
.Xr kill 1
|
|
|
|
utility, a certain action will be triggered.
|
|
|
|
.Bl -tag -width -Ds
|
|
|
|
.It Cd SIGHUP
|
|
|
|
Rereads the playlist file after the track that is currently streamed.
|
|
|
|
If the playlist is not to be shuffled,
|
|
|
|
.Nm
|
|
|
|
attempts to find the previously streamed file and continue with the one
|
|
|
|
following it, or restarts from the beginning of the list otherwise.
|
|
|
|
.It Cd SIGUSR1
|
|
|
|
Skips the currently playing track and moves on to the next in playlist mode, or
|
|
|
|
restarts the current track when streaming a single file.
|
2007-03-08 21:30:29 -05:00
|
|
|
.It Cd SIGUSR2
|
|
|
|
Triggers rereading of metadata for the stream by running the program or script
|
2007-03-10 19:02:20 -05:00
|
|
|
specified in
|
|
|
|
.Li \&<metadata_progname/\&>
|
2007-03-08 21:30:29 -05:00
|
|
|
.Pq see below.
|
|
|
|
This is the only meaningful signal when streaming from standard input.
|
2007-02-24 15:52:57 -05:00
|
|
|
.El
|
|
|
|
.Pp
|
|
|
|
.Sh CONFIGURATION FILE SYNTAX
|
|
|
|
The
|
|
|
|
.Nm
|
|
|
|
utility uses a simple XML configuration file format.
|
|
|
|
It has a tree-like structure and is made up of
|
|
|
|
.Em XML elements .
|
|
|
|
Of all the possible XML features, only regular elements that contain text or
|
|
|
|
other elements, and comments, appear in an
|
|
|
|
.Nm
|
|
|
|
configuration file.
|
|
|
|
.Pp
|
|
|
|
Each element in the configuration file consists of a
|
2007-03-10 19:02:20 -05:00
|
|
|
.Em start tag ,
|
2015-05-14 17:29:38 -04:00
|
|
|
its content, and an
|
2007-03-10 19:02:20 -05:00
|
|
|
.Em end tag .
|
2007-02-24 15:52:57 -05:00
|
|
|
For example:
|
|
|
|
.Pp
|
|
|
|
.Dl \&<filename\&>playlist.m3u<\&/filename\&>
|
|
|
|
.Dl \&<\&!-- XML comments look like this. --\&>
|
|
|
|
.Sh XML CONFIGURATION
|
|
|
|
In this section, each available element is listed and described.
|
|
|
|
Note that for this purpose, elements are introduced in their short, i.e. empty
|
|
|
|
form.
|
|
|
|
In the configuration file, they need to be used as
|
|
|
|
.Em start tag + content + end tag ,
|
|
|
|
like in the introductory example shown above.
|
|
|
|
.Ss Root element
|
2007-03-08 21:30:29 -05:00
|
|
|
.Bl -tag -width -Ds
|
2007-02-24 15:52:57 -05:00
|
|
|
.It Sy \&<ezstream\ /\&>
|
|
|
|
.Pq Mandatory.
|
|
|
|
The configuration file's root element.
|
2015-05-14 17:29:38 -04:00
|
|
|
It contains all other configuration elements:
|
|
|
|
.Pp
|
2007-02-24 15:52:57 -05:00
|
|
|
.El
|
2015-05-14 17:29:38 -04:00
|
|
|
.Ss Server block
|
2007-03-08 21:30:29 -05:00
|
|
|
.Bl -tag -width -Ds
|
2015-05-14 17:29:38 -04:00
|
|
|
.It Sy \&<server\ /\&>
|
2007-02-24 15:52:57 -05:00
|
|
|
.Pq Mandatory.
|
2015-05-14 17:29:38 -04:00
|
|
|
This element contains the entire server configuration as child elements.
|
|
|
|
Its parent is the
|
|
|
|
.Sy \&<ezstream\ /\&>
|
|
|
|
element.
|
|
|
|
.El
|
|
|
|
.Ss Server configuration
|
|
|
|
.Bl -tag -width -Ds
|
|
|
|
.It Sy \&<protocol\ /\&>
|
|
|
|
Transport protocol used to stream to the server:
|
2007-02-24 15:52:57 -05:00
|
|
|
.Pp
|
2015-05-14 17:29:38 -04:00
|
|
|
.Bl -tag -width HTTPS -compact
|
|
|
|
.It Ar HTTP
|
|
|
|
Unencrypted HTTP (the default).
|
|
|
|
.It Ar HTTPS
|
|
|
|
HTTP over TLS.
|
|
|
|
.El
|
|
|
|
.It Sy \&<hostname\ /\&>
|
|
|
|
.Pq Mandatory.
|
|
|
|
The FQDN host name or IP address of the server.
|
|
|
|
.It Sy \&<port\ /\&>
|
|
|
|
Port number on which the server is listening.
|
|
|
|
.Pp
|
|
|
|
Default:
|
|
|
|
.Ar 8000
|
|
|
|
.It Sy \&<user\ /\&>
|
|
|
|
User to authenticate as on the server.
|
|
|
|
.Pp
|
|
|
|
Default:
|
|
|
|
.Ar source
|
|
|
|
.It Sy \&<password\ /\&>
|
|
|
|
.Pq Mandatory.
|
|
|
|
Password to authenticate with on the server.
|
|
|
|
.It Sy \&<ca_dir\ /\&>
|
|
|
|
Directory in which OpenSSL finds root CA certificates for validating the
|
|
|
|
.Ar HTTPS
|
|
|
|
server identity.
|
|
|
|
.Pp
|
|
|
|
Default:
|
|
|
|
.Em no server validation
|
|
|
|
.It Sy \&<ca_file\ /\&>
|
|
|
|
Path of a root CA bundle file for validating the
|
|
|
|
.Ar HTTPS
|
|
|
|
server identity.
|
|
|
|
.Pp
|
|
|
|
Default:
|
|
|
|
.Em no server validation
|
|
|
|
.It Sy \&<client_cert\ /\&>
|
|
|
|
X.503 client certificate for authentication on an
|
|
|
|
.Ar HTTPS
|
|
|
|
server.
|
|
|
|
.Pp
|
|
|
|
Default:
|
|
|
|
.Em no client certificate authentication
|
|
|
|
.It Sy \&<client_key\ /\&>
|
|
|
|
Private key that matches the public key and certificate in
|
|
|
|
.Sy \&<client_cert\ /\&> .
|
|
|
|
.Pp
|
|
|
|
Default:
|
|
|
|
.Em no client certificate authentication
|
|
|
|
.It Sy \&<reconnect_attempts\ /\&>
|
|
|
|
Number of reconnect attempts in case of connection issues with the server,
|
|
|
|
or 0
|
|
|
|
.Pq zero
|
|
|
|
for trying indefinitely (the default).
|
|
|
|
.El
|
|
|
|
.Ss Stream block
|
|
|
|
.Bl -tag -width -Ds
|
|
|
|
.It Sy \&<stream\ /\&>
|
|
|
|
.Pq Mandatory.
|
|
|
|
This element contains the entire stream configuration as child elements.
|
|
|
|
Its parent is the
|
|
|
|
.Sy \&<ezstream\ /\&>
|
|
|
|
element.
|
|
|
|
.El
|
|
|
|
.Ss Stream configuration
|
|
|
|
.Bl -tag -width -Ds
|
|
|
|
.It Sy \&<mountpoint\ /\&>
|
2007-02-24 15:52:57 -05:00
|
|
|
.Pq Mandatory.
|
2015-05-14 17:29:38 -04:00
|
|
|
Stream mountpoint on the server.
|
|
|
|
.It Sy \&<name\ /\&>
|
|
|
|
Informational name of the broadcast.
|
|
|
|
.Pp
|
|
|
|
Default:
|
|
|
|
.Em none
|
|
|
|
.It Sy \&<url\ /\&>
|
|
|
|
Informational URL associated with the broadcast, e.g. the web site.
|
|
|
|
.Pp
|
|
|
|
Default:
|
|
|
|
.Em none
|
|
|
|
.It Sy \&<genre\ /\&>
|
|
|
|
Informational genre of the broadcast.
|
|
|
|
.Pp
|
|
|
|
Default:
|
|
|
|
.Em none
|
|
|
|
.It Sy \&<description\ /\&>
|
|
|
|
Informational description of the broadcast.
|
|
|
|
.Pp
|
|
|
|
Default:
|
|
|
|
.Em none
|
|
|
|
.It Sy \&<quality\ /\&>
|
|
|
|
Informational quality setting of the VBR broadcast.
|
|
|
|
.Pp
|
|
|
|
Default:
|
|
|
|
.Em none
|
|
|
|
.It Sy \&<bitrate\ /\&>
|
|
|
|
Informational bitrate setting of the CBR broadcast.
|
|
|
|
.Pp
|
|
|
|
Default:
|
|
|
|
.Em none
|
|
|
|
.It Sy \&<samplerate\ /\&>
|
|
|
|
Informational sample rate of the broadcast audio.
|
|
|
|
.Pp
|
|
|
|
Default:
|
|
|
|
.Em none
|
|
|
|
.It Sy \&<channels\ /\&>
|
|
|
|
Informational number of audio channels of the broadcast.
|
|
|
|
.Pp
|
|
|
|
Default:
|
|
|
|
.Em none
|
|
|
|
.It Sy \&<server_public\ /\&>
|
|
|
|
Boolean setting of whether the broadcast may be listed in a public YP
|
|
|
|
directory, or not.
|
|
|
|
.Pp
|
|
|
|
.Bl -tag -width 0|NO|FALSE -compact
|
|
|
|
.It Ar 0|No|False
|
|
|
|
The broadcast is private (the default).
|
|
|
|
.It Ar 1|Yes|True
|
|
|
|
The broadcast is public.
|
|
|
|
.El
|
2007-02-24 15:52:57 -05:00
|
|
|
.It Sy \&<format\ /\&>
|
|
|
|
.Pq Mandatory.
|
2015-05-14 17:29:38 -04:00
|
|
|
The stream format.
|
|
|
|
.Pp
|
|
|
|
.Bl -tag -width VORBIS -compact
|
|
|
|
.It Ar Vorbis
|
|
|
|
Ogg Vorbis audio format
|
|
|
|
.It Ar MP3
|
|
|
|
MP3 audio format
|
|
|
|
.It Ar Theora
|
|
|
|
Ogg Theora video format
|
|
|
|
.El
|
|
|
|
.It Sy \&<encoder\ /\&>
|
|
|
|
Set the encoder by its configured symbolic name
|
|
|
|
.Pq see below ,
|
|
|
|
which should be used to (re)encode the stream.
|
|
|
|
Not configuring an encoder makes
|
2007-02-24 15:52:57 -05:00
|
|
|
.Nm
|
2015-05-14 17:29:38 -04:00
|
|
|
stream input media files as-is.
|
|
|
|
.Pp
|
|
|
|
The configured encoder's output stream format must match what is configured
|
|
|
|
in
|
|
|
|
.Sy \&<format\ /\&> .
|
|
|
|
.El
|
|
|
|
.Ss Media block
|
|
|
|
.Bl -tag -width -Ds
|
|
|
|
.It Sy \&<media\ /\&>
|
2007-02-24 15:52:57 -05:00
|
|
|
.Pq Mandatory.
|
2015-05-14 17:29:38 -04:00
|
|
|
This element contains the entire input media configuration as child elements.
|
|
|
|
Its parent is the
|
|
|
|
.Sy \&<ezstream\ /\&>
|
|
|
|
element.
|
|
|
|
.El
|
|
|
|
.Ss Media configuration
|
|
|
|
.Bl -tag -width -Ds
|
|
|
|
.It Sy \&<type\ /\&>
|
|
|
|
Configure the input media type:
|
|
|
|
.Pp
|
|
|
|
.Bl -tag -width AUTODETECT -compact
|
|
|
|
.It Ar autodetect
|
|
|
|
Attempt to autodetect, whether the input is a playlist, or a single media
|
|
|
|
file.
|
|
|
|
Playlists are detected by their
|
|
|
|
.Dq Li .m3u
|
|
|
|
and
|
|
|
|
.Dq Li .txt
|
|
|
|
file name extensions.
|
|
|
|
.Pq This is the default.
|
|
|
|
.It Ar file
|
|
|
|
The input is one single media file.
|
|
|
|
.It Ar playlist
|
|
|
|
The input is a playlist.
|
|
|
|
Playlists are a newline-delimited list of media file path names.
|
2007-02-24 15:52:57 -05:00
|
|
|
Comments in playlists are introduced by a
|
|
|
|
.Sq Li #
|
|
|
|
sign at the beginning of a line and ignored by
|
|
|
|
.Nm .
|
2015-05-14 17:29:38 -04:00
|
|
|
.It Ar program
|
|
|
|
The input is an executable
|
|
|
|
.Dq Playlist Program .
|
|
|
|
See
|
|
|
|
.Xr SCRIPTING
|
|
|
|
for more information.
|
|
|
|
.It Ar stdin
|
|
|
|
The input is read from standard input.
|
|
|
|
.El
|
|
|
|
.It Sy \&<filename\ /\&>
|
|
|
|
The input media file name; mandatory for all but the
|
|
|
|
.Ar stdin
|
|
|
|
type.
|
2007-02-24 15:52:57 -05:00
|
|
|
.It Sy \&<shuffle\ /\&>
|
2015-05-14 17:29:38 -04:00
|
|
|
Boolean setting of whether the
|
|
|
|
.Ar playlist
|
|
|
|
type media should be shuffled, or not.
|
|
|
|
.Pp
|
|
|
|
.Bl -tag -width 0|NO|FALSE -compact
|
|
|
|
.It Ar 0|No|False
|
|
|
|
Stream the playlist content sequentially (the default).
|
|
|
|
.It Ar 1|Yes|True
|
|
|
|
Shuffle the playlist prior to streaming its content.
|
|
|
|
.El
|
|
|
|
.It Sy \&<stream_once\ /\&>
|
|
|
|
Boolean setting of whether
|
2007-03-08 21:30:29 -05:00
|
|
|
.Nm
|
2015-05-14 17:29:38 -04:00
|
|
|
should exit after streaming its media input, or start over.
|
2007-03-08 21:30:29 -05:00
|
|
|
.Pp
|
2015-05-14 17:29:38 -04:00
|
|
|
.Bl -tag -width 0|NO|FALSE -compact
|
|
|
|
.It Ar 0|No|False
|
|
|
|
Attempt to start over whenever the end of the media input is reached (the
|
|
|
|
default).
|
|
|
|
.It Ar 1|Yes|True
|
|
|
|
After streaming all media input, exit.
|
|
|
|
.El
|
|
|
|
.El
|
|
|
|
.Ss Metadata block
|
|
|
|
.Bl -tag -width -Ds
|
|
|
|
.It Sy \&<metadata\ /\&>
|
|
|
|
.Pq Mandatory.
|
|
|
|
This element contains the entire metadata configuration as child elements.
|
|
|
|
Its parent is the
|
|
|
|
.Sy \&<ezstream\ /\&>
|
|
|
|
element.
|
|
|
|
.El
|
|
|
|
.Ss Metadata configuration
|
|
|
|
.Bl -tag -width -Ds
|
|
|
|
.It Sy \&<program\ /\&>
|
|
|
|
Set an executable
|
|
|
|
.Dq Metadata Program
|
|
|
|
to be queried for all metadata on
|
|
|
|
.Sy SIGUSR2
|
|
|
|
or whenever a new track begins.
|
|
|
|
See
|
|
|
|
.Xr SCRIPTING
|
|
|
|
for more information.
|
2007-03-08 21:30:29 -05:00
|
|
|
.Pp
|
2015-05-14 17:29:38 -04:00
|
|
|
Default:
|
|
|
|
.Em use metadata as contained in media files
|
|
|
|
.It Sy \&<format_str\ /\&>
|
2007-03-10 14:03:07 -05:00
|
|
|
Set the format of the string that should be used for the
|
2007-03-10 19:02:20 -05:00
|
|
|
.Sq Li @M@
|
2015-05-14 17:29:38 -04:00
|
|
|
placeholder, when quering for metadata from an executable.
|
2007-03-10 14:03:07 -05:00
|
|
|
.Pp
|
2015-05-14 17:29:38 -04:00
|
|
|
Default:
|
|
|
|
.Em Li @A@ - @T@
|
|
|
|
.It Sy \&<refresh_interval\ /\&>
|
|
|
|
Configure a time interval for additional metadata updates via a
|
|
|
|
.Dq Metadata Program :
|
|
|
|
.Pp
|
|
|
|
.Bl -tag -width -1 -compact
|
|
|
|
.It Ar -1
|
|
|
|
Do not trigger any additional metadata updates (the default).
|
|
|
|
.It Ar 0
|
|
|
|
Trigger metadata updates at the highest reasonable frequency.
|
|
|
|
.It Ar \&>0
|
|
|
|
Configure the time
|
2010-06-21 14:39:26 -04:00
|
|
|
.Pq in seconds
|
2015-05-14 17:29:38 -04:00
|
|
|
in between additional metadata updates.
|
|
|
|
.El
|
|
|
|
.It Sy \&<normalize_strings\ /\&>
|
|
|
|
Boolean setting of whether metadata strings should have excess whitespace
|
|
|
|
removed, or not.
|
|
|
|
.Pp
|
|
|
|
.Bl -tag -width 0|NO|FALSE -compact
|
|
|
|
.It Ar 0|No|False
|
|
|
|
Use metadata strings as-is (the default).
|
|
|
|
.It Ar 1|Yes|True
|
|
|
|
Trim leading and trailing whitespace, as well as remove excess whitespace
|
|
|
|
in case that there is more than one in sequence.
|
2007-02-24 15:52:57 -05:00
|
|
|
.El
|
2015-05-14 17:29:38 -04:00
|
|
|
.It Sy \&<no_updates\ /\&>
|
|
|
|
Boolean setting of whether metadata updates should be suppressed altogether,
|
|
|
|
or not.
|
|
|
|
.Pp
|
|
|
|
.Bl -tag -width 0|NO|FALSE -compact
|
|
|
|
.It Ar 0|No|False
|
|
|
|
Update metadata in the usual manner (the default).
|
|
|
|
.It Ar 1|Yes|True
|
|
|
|
Disable all metadata updates, and keep existing metadata in streams untouched.
|
|
|
|
.El
|
|
|
|
.El
|
|
|
|
.Ss Decoders block
|
2007-03-08 21:30:29 -05:00
|
|
|
.Bl -tag -width -Ds
|
2015-05-14 17:29:38 -04:00
|
|
|
.It Sy \&<decoders\ /\&>
|
|
|
|
This element contains all decoder blocks as child elements.
|
|
|
|
Its parent is the
|
|
|
|
.Sy \&<ezstream\ /\&>
|
2007-03-10 19:02:20 -05:00
|
|
|
element.
|
2007-02-24 15:52:57 -05:00
|
|
|
.El
|
2015-05-14 17:29:38 -04:00
|
|
|
.Ss Decoder block
|
2007-03-08 21:30:29 -05:00
|
|
|
.Bl -tag -width -Ds
|
2015-05-14 17:29:38 -04:00
|
|
|
.It Sy \&<decoder\ /\&>
|
|
|
|
This element contains all configuration of a single decoder.
|
|
|
|
Its parent is the
|
|
|
|
.Sy \&<decoders\ /\&>
|
|
|
|
element.
|
2007-02-24 15:52:57 -05:00
|
|
|
.Pp
|
2015-05-14 17:29:38 -04:00
|
|
|
Many decoders can be configured, but a filename extension can only be
|
|
|
|
associated with one decoder.
|
|
|
|
.El
|
|
|
|
.Ss Decoder configuration
|
|
|
|
.Bl -tag -width -Ds
|
|
|
|
.It Sy \&<name\ /\&>
|
|
|
|
Set the name of the decoder configuration.
|
|
|
|
Choosing a meaningful, unique name is beneficial for logging and debugging.
|
|
|
|
.Pp
|
|
|
|
Default:
|
|
|
|
.Em autoincrementing index
|
|
|
|
.It Sy \&<program\ /\&>
|
|
|
|
.Pq Mandatory.
|
|
|
|
Set the full command line to decode a media input file, represented by the
|
|
|
|
.Sq @T@
|
|
|
|
placeholder, into a
|
|
|
|
.Dq canonical internal format
|
|
|
|
on standard output.
|
2007-02-24 15:52:57 -05:00
|
|
|
.Pp
|
2015-05-14 17:29:38 -04:00
|
|
|
The canonical format should be the same for all configured decoders, e.g. RAW
|
|
|
|
audio with a specific signedness, bitrate, and samplerate that can be
|
|
|
|
consumed by encoders.
|
2007-03-10 14:03:07 -05:00
|
|
|
.Pp
|
2015-05-14 17:29:38 -04:00
|
|
|
For exotic use cases, metadata placeholders may be used here.
|
|
|
|
.Pp
|
|
|
|
Example:
|
|
|
|
.Dl \&<program\&>oggdec -R -o - @T@\&</program\&>
|
|
|
|
.It Sy \&<file_ext\ /\&>
|
|
|
|
.Pq Mandatory.
|
|
|
|
Set a filename extension to be associated with this decoder.
|
|
|
|
.Pp
|
|
|
|
It is possible to specify more than one
|
|
|
|
.Sy \&<file_ext\ /\&>
|
|
|
|
element per decoder to associate more than one file extension to the same
|
|
|
|
decoder.
|
|
|
|
.El
|
|
|
|
.Ss Encoders block
|
|
|
|
.Bl -tag -width -Ds
|
|
|
|
.It Sy \&<encoders\ /\&>
|
|
|
|
This element contains all encoder blocks as child elements.
|
|
|
|
Its parent is the
|
|
|
|
.Sy \&<ezstream\ /\&>
|
2007-03-10 19:02:20 -05:00
|
|
|
element.
|
2015-05-14 17:29:38 -04:00
|
|
|
.El
|
|
|
|
.Ss Encoder block
|
|
|
|
.Bl -tag -width -Ds
|
|
|
|
.It Sy \&<encoder\ /\&>
|
|
|
|
This element contains all configuration of a single encoder.
|
|
|
|
Its parent is the
|
|
|
|
.Sy \&<encoders\ /\&>
|
|
|
|
element.
|
|
|
|
.Pp
|
|
|
|
Many encoders can be configured.
|
|
|
|
.El
|
|
|
|
.Ss Encoder configuration
|
|
|
|
.Bl -tag -width -Ds
|
|
|
|
.It Sy \&<name\ /\&>
|
|
|
|
.Pq Mandatory.
|
|
|
|
Set the name of the encoder configuration, to be referenced in the
|
|
|
|
.Sy \&<stream\ /\&>
|
|
|
|
block in case (re)encoding is desired.
|
|
|
|
.Pp
|
|
|
|
The name is case-aware, but not case-sensitive.
|
|
|
|
.It Sy \&<format\ /\&>
|
|
|
|
.Pq Mandatory.
|
|
|
|
Stream format produced by this encoder.
|
|
|
|
This must be one of the available stream formats as specified for the
|
|
|
|
.Sy \&<stream\ /\&>
|
|
|
|
block.
|
|
|
|
.It Sy \&<program\ /\&>
|
|
|
|
.Pq Mandatory.
|
|
|
|
Set the full command line to encode
|
|
|
|
.Dq canonical internal format
|
|
|
|
from standard input into a supported stream format on standard output.
|
2007-02-24 15:52:57 -05:00
|
|
|
.Pp
|
2015-05-14 17:29:38 -04:00
|
|
|
Metadata placeholders may be used here.
|
2007-02-24 15:52:57 -05:00
|
|
|
.Pp
|
2015-05-14 17:29:38 -04:00
|
|
|
Example:
|
|
|
|
.Dl \&<program\&>oggenc -r -q 1.5 -t @M@ -\&</program\&>
|
2007-02-24 15:52:57 -05:00
|
|
|
.El
|
2007-03-08 21:30:29 -05:00
|
|
|
.Sh SCRIPTING
|
|
|
|
The
|
|
|
|
.Nm
|
|
|
|
utility provides hooks for externally controlled playlist and metadata
|
|
|
|
management.
|
|
|
|
This is done by running external programs or scripts that need to behave in
|
|
|
|
ways explained here.
|
|
|
|
.Ss Common Rules
|
|
|
|
.Bl -dash -compact
|
|
|
|
.It
|
|
|
|
The program must be an executable file.
|
|
|
|
.It
|
|
|
|
The program must write one line to standard output and exit.
|
|
|
|
.It
|
2007-07-13 06:30:58 -04:00
|
|
|
The program must not require arbitrary command line options to function.
|
2007-03-08 21:30:29 -05:00
|
|
|
A wrapper script must be used if there is no other way.
|
|
|
|
.El
|
|
|
|
.Ss Playlist Programs
|
|
|
|
.Bl -dash -compact
|
|
|
|
.It
|
|
|
|
The program must return only filenames, with one filename per execution.
|
|
|
|
.It
|
|
|
|
The program should not return an empty line unless
|
|
|
|
.Nm
|
|
|
|
is supposed to know that the end of the playlist has been reached.
|
2007-03-10 19:02:20 -05:00
|
|
|
This is significant when the
|
|
|
|
.Li \&<stream_once/\&>
|
|
|
|
option is enabled.
|
2007-03-08 21:30:29 -05:00
|
|
|
.El
|
|
|
|
.Ss Metadata Programs
|
|
|
|
.Bl -dash -compact
|
|
|
|
.It
|
|
|
|
The program must not return anything (just a newline character is okay) if it
|
|
|
|
is called by
|
|
|
|
.Nm
|
2015-05-14 17:29:38 -04:00
|
|
|
with a command line argument that the program does not support.
|
2007-03-08 21:30:29 -05:00
|
|
|
.It
|
2015-05-14 17:29:38 -04:00
|
|
|
When called without command line arguments, the program should return a
|
2007-03-08 21:30:29 -05:00
|
|
|
complete string that should be used for metadata.
|
|
|
|
.It
|
2015-05-14 17:29:38 -04:00
|
|
|
When called with the command line argument
|
2007-03-10 19:02:20 -05:00
|
|
|
.Qq Li artist ,
|
2007-03-08 21:30:29 -05:00
|
|
|
the program should return only the artist information of the metadata.
|
|
|
|
.Pq Optional.
|
|
|
|
.It
|
2015-05-14 17:29:38 -04:00
|
|
|
When called with the command line argument
|
2007-03-10 19:02:20 -05:00
|
|
|
.Qq Li title ,
|
2007-03-08 21:30:29 -05:00
|
|
|
the program should return only the title information of the metadata.
|
|
|
|
.Pq Optional.
|
2007-08-24 07:57:09 -04:00
|
|
|
.It
|
2007-08-30 08:13:01 -04:00
|
|
|
The supplied metadata must be encoded in UTF-8.
|
2007-03-08 21:30:29 -05:00
|
|
|
.El
|
2007-03-10 14:03:07 -05:00
|
|
|
.Sh METADATA
|
|
|
|
The main tool for handling metadata with
|
|
|
|
.Nm
|
|
|
|
is placeholders in decoder and encoder commands that are replaced with real
|
|
|
|
content during runtime.
|
2015-01-07 16:49:09 -05:00
|
|
|
.Pp
|
|
|
|
.Em Note:
|
2015-05-14 17:29:38 -04:00
|
|
|
All placeholders are replaced with content enclosed in single quotes, with
|
|
|
|
escaped single quote and backslash characters in between, so that
|
|
|
|
interpretation by the shell does not occur.
|
|
|
|
.Em Do not add any additional quoting!
|
2007-03-10 14:03:07 -05:00
|
|
|
.Ss Metadata Placeholders
|
|
|
|
.Bl -tag -width -Ds
|
|
|
|
.It Sy @T@
|
|
|
|
Replaced with the media file name.
|
2007-03-10 19:02:20 -05:00
|
|
|
Required in
|
2015-05-14 17:29:38 -04:00
|
|
|
.Li /ezstream/decoders/decoder/program .
|
|
|
|
Available in
|
|
|
|
.Li /ezstream/metadata/format_str .
|
2007-03-10 14:03:07 -05:00
|
|
|
.It Sy @M@
|
|
|
|
Replaced with a metadata string.
|
2015-05-14 17:29:38 -04:00
|
|
|
.Pq See below for a detailed explanation.
|
2007-03-10 19:02:20 -05:00
|
|
|
Available in
|
2015-05-14 17:29:38 -04:00
|
|
|
.Li /ezstream/decoders/decoder/program
|
2007-03-10 19:02:20 -05:00
|
|
|
and
|
2015-05-14 17:29:38 -04:00
|
|
|
.Li /ezstream/encoders/encoder/program .
|
2007-03-10 14:03:07 -05:00
|
|
|
.It Sy @a@
|
|
|
|
Replaced with the artist information.
|
2007-03-10 19:02:20 -05:00
|
|
|
Available in
|
2015-05-14 17:29:38 -04:00
|
|
|
.Li /ezstream/decoders/decoder/program ,
|
|
|
|
.Li /ezstream/encoders/encoder/program
|
2007-03-10 19:02:20 -05:00
|
|
|
and
|
2015-05-14 17:29:38 -04:00
|
|
|
.Li /ezstream/metadata/format_str .
|
2007-03-10 14:03:07 -05:00
|
|
|
.It Sy @t@
|
|
|
|
Replaced with the title information.
|
2007-03-10 19:02:20 -05:00
|
|
|
Available in
|
2015-05-14 17:29:38 -04:00
|
|
|
.Li /ezstream/decoders/decoder/program ,
|
|
|
|
.Li /ezstream/encoders/encoder/program
|
2007-03-10 19:02:20 -05:00
|
|
|
and
|
2015-05-14 17:29:38 -04:00
|
|
|
.Li /ezstream/metadata/format_str .
|
2007-03-10 14:03:07 -05:00
|
|
|
.It Sy @s@
|
2007-03-10 19:02:20 -05:00
|
|
|
Replaced with the string returned by
|
2015-05-14 17:29:38 -04:00
|
|
|
.Li /ezstream/metadata/program
|
|
|
|
when called without any command line arguments.
|
2007-03-10 19:02:20 -05:00
|
|
|
Available only in
|
2015-05-14 17:29:38 -04:00
|
|
|
.Li /ezstream/metadata/format_str .
|
2007-03-10 14:03:07 -05:00
|
|
|
.El
|
|
|
|
.Ss The @M@ Placeholder
|
|
|
|
While all other placeholders are simply replaced with whatever data they are
|
|
|
|
associated with,
|
2007-03-10 19:02:20 -05:00
|
|
|
.Sq Li @M@
|
2007-03-10 14:03:07 -05:00
|
|
|
is context-sensitive.
|
|
|
|
The logic used by
|
|
|
|
.Nm
|
|
|
|
is the following:
|
|
|
|
.Bd -literal -offset indent
|
|
|
|
If ('@M@ is present')
|
2015-05-14 17:29:38 -04:00
|
|
|
If (/ezstream/metadata/program AND /ezstream/metadata/format_str)
|
2007-03-10 14:03:07 -05:00
|
|
|
Replace with format string result.
|
|
|
|
Else
|
2015-05-14 17:29:38 -04:00
|
|
|
If (NOT /ezstream/metadata/program AND '@t@ is present')
|
2007-03-10 14:03:07 -05:00
|
|
|
Replace with empty string.
|
|
|
|
else
|
|
|
|
Replace with generated metadata string.
|
|
|
|
Endif
|
|
|
|
Endif
|
|
|
|
Endif
|
|
|
|
.Ed
|
|
|
|
.Pp
|
|
|
|
The generated metadata string for
|
2007-03-10 19:02:20 -05:00
|
|
|
.Sq Li @M@
|
2007-03-10 14:03:07 -05:00
|
|
|
is of the format
|
2007-03-10 19:02:20 -05:00
|
|
|
.Dq Em Artist - Title ,
|
2007-03-10 14:03:07 -05:00
|
|
|
if both artist and title information is available.
|
|
|
|
If one of the two is missing, the available one is displayed without a leading
|
|
|
|
or trailing dash, e.g. just
|
2007-03-10 19:02:20 -05:00
|
|
|
.Dq Em Artist .
|
|
|
|
If neither artist nor title are available, the name of the media file \(em
|
|
|
|
without its file extension \(em is used.
|
2007-03-10 14:03:07 -05:00
|
|
|
.Ss Metadata Caveats
|
|
|
|
It is possible to generate strange results with odd combinations of
|
|
|
|
placeholders, external metadata programs and updates during runtime via
|
|
|
|
.Sy SIGUSR2 .
|
|
|
|
If things start to become just confusing, simplify.
|
|
|
|
.Pp
|
2015-05-14 17:29:38 -04:00
|
|
|
Metadata updates during runtime are done with a eccentric feature of libshout.
|
2007-03-10 14:03:07 -05:00
|
|
|
Additional metadata information that is already present in the stream sent via
|
|
|
|
.Nm
|
|
|
|
is usually destroyed and replaced with the new data.
|
|
|
|
It is not possible to properly discern between artist and title information,
|
|
|
|
which means that anything set with the
|
|
|
|
.Sy SIGUSR2
|
|
|
|
feature will continue to end up entirely in the
|
2007-03-10 19:02:20 -05:00
|
|
|
.Qq Em Title
|
2007-03-10 14:03:07 -05:00
|
|
|
field of a stream.
|
2007-08-25 11:07:38 -04:00
|
|
|
.Pp
|
2015-05-14 17:29:38 -04:00
|
|
|
Additional limitations in Icecast may apply as well, where one historic
|
|
|
|
example is that of all possible Ogg-based streams, only Ogg Vorbis can have
|
|
|
|
its metadata manipulated.
|
2007-08-25 11:07:38 -04:00
|
|
|
.Pp
|
2015-05-14 17:29:38 -04:00
|
|
|
The ID3v1 tags
|
|
|
|
.Pq relevant when streaming in MP3 format
|
|
|
|
do not specify any character encoding, so
|
2007-08-25 11:07:38 -04:00
|
|
|
.Nm
|
2015-05-14 17:29:38 -04:00
|
|
|
operates in a manner of
|
|
|
|
.Dq best effort .
|
|
|
|
In case of encoding issues, it may help to explicitly set a codeset to work
|
|
|
|
with via the
|
2007-08-25 11:07:38 -04:00
|
|
|
.Ev LC_CTYPE
|
2007-08-30 08:13:01 -04:00
|
|
|
environment variable, as
|
|
|
|
.Nm
|
|
|
|
assumes ID3v1 tags to be in the user's current locale.
|
|
|
|
Note that, even though support for different locales is provided by
|
|
|
|
.Nm ,
|
|
|
|
Icecast itself and the listening clients also have a say in the matter.
|
|
|
|
The only way to ensure consistent results with metadata in non-Ogg streams is
|
2015-05-14 17:29:38 -04:00
|
|
|
to use only the characters available in the ISO-8859-1 codeset.
|
2007-08-25 11:07:38 -04:00
|
|
|
.Pp
|
|
|
|
External encoders may put additional, and possibly artificial, restrictions on
|
|
|
|
valid characters in metadata.
|
2007-02-24 15:52:57 -05:00
|
|
|
.Sh FILES
|
|
|
|
.Bl -tag -width "!!EXAMPLES_DIR!!" -compact
|
|
|
|
.It Pa !!EXAMPLES_DIR!!
|
|
|
|
Directory containing example configuration files for various uses of
|
2007-03-10 14:03:07 -05:00
|
|
|
.Nm ,
|
|
|
|
as well as example playlist and metadata scripts.
|
2007-02-24 15:52:57 -05:00
|
|
|
.El
|
2009-08-30 08:49:06 -04:00
|
|
|
.Sh SEE ALSO
|
|
|
|
.Xr ezstream-file.sh 1
|
2007-02-24 15:52:57 -05:00
|
|
|
.Sh AUTHORS
|
|
|
|
.Nm
|
|
|
|
was written by:
|
|
|
|
.Pp
|
|
|
|
.An Ed Zaleski Aq oddsock@oddsock.org
|
2015-01-07 17:44:44 -05:00
|
|
|
.An Moritz Grimm Aq mgrimm@mrsserver.net
|
2007-02-24 15:52:57 -05:00
|
|
|
.Pp
|
2015-01-07 17:44:44 -05:00
|
|
|
.An -nosplit
|
|
|
|
This manual was written by
|
|
|
|
.An Moritz Grimm .
|