Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
EZSTREAM(1)		  BSD General Commands Manual		   EZSTREAM(1)

     ezstream -- source	client for Icecast with	external de-/encoder support

     ezstream [-hnqVv] -c configfile
     ezstream -s [playlist]

     The ezstream 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 "as-is" -- such as Ogg	Vorbis,	Ogg Theora and MP3 --
     to	a server.  It can also use various external decoders and encoders to
     re-encode from one	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.

   Command line	parameters
     -c	configfile
	     Use the XML configuration in configfile.

     -h	     Print a summary of	available command line parameters with short
	     descriptions and exit.

     -n	     Normalize metadata	strings	by removing excess whitespaces.

     -q	     Be	more quiet.  Suppress the output that external programs	send
	     to	standard error.

     -s	[playlist]
	     Run ezstream as a line-based shuffling utility.  If no playlist
	     argument is given,	a list of media	file names is read from	stan-
	     dard input	instead	of an input file.  After successfully reading
	     the entire	list, it is shuffled and printed to standard output,
	     and ezstream will exit.

     -V	     Print the ezstream	version	number and exit.

     -v	     Produce more verbose output from ezstream.	 Use twice for even
	     more verbose output.

     When the -q and -v	parameters are provided	simultaneously,	an additional
     line of information about the currently streamed file -- playlist posi-
     tion, approximate playing time and	bit rate -- is displayed.

   Runtime control
     On	POSIX systems, ezstream	offers limited runtime control via signals.
     By	sending	a signal to the	ezstream process, e.g. with the	kill(1)	util-
     ity, a certain action will	be triggered.

	  Rereads the playlist file after the track that is currently
	  streamed.  If	the playlist is	not to be shuffled, ezstream attempts
	  to find the previously streamed file and continue with the one fol-
	  lowing it, or	restarts from the beginning of the list	otherwise.

	  Skips	the currently playing track and	moves on to the	next in
	  playlist mode, or restarts the current track when streaming a	single

	  Triggers rereading of	metadata for the stream	by running the program
	  or script specified in <metadata_progname/> (see below.) This	is the
	  only meaningful signal when streaming	from standard input.

     The ezstream utility uses a simple	XML configuration file format.	It has
     a tree-like structure and is made up of XML elements.  Of all the possi-
     ble XML features, only regular elements that contain text or other	ele-
     ments, and	comments, appear in an ezstream	configuration file.

     Each element in the configuration file consists of	a start	tag, its con-
     tent and an end tag.  For example:

	   <!--	XML comments look like this. -->

     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 start tag +
     content + end tag,	like in	the introductory example shown above.

   Root	element
     <ezstream />
	  (Mandatory.) The configuration file's	root element.  It contains all
	  other	configuration elements.

   Global configuration	elements
     Each of the global	configuration elements have the	<ezstream/> element as
     their parent.

     <url />
	  (Mandatory.) Specifies the location and mount	point of the Icecast
	  server, to which the stream will be sent.  The content must be of
	  the form http://server:port/mountpoint For example:


     <sourceuser />
	  (Optional.) Sets the source username for authentication with the
	  Icecast server.  The default user (usually "source") is used if this
	  element is not provided.

     <sourcepassword />
	  (Mandatory.) Sets the	source password	for authentication with	the
	  Icecast server.

     <format />
	  (Mandatory.) This element has	two different meanings,	depending on
	  whether re-encoding is enabled or not.  It specifies the output
	  format of the	stream if re-encoding is enabled.  Otherwise, it spec-
	  ifies	the input format of all	input files.  Recognized and supported
	  values for output stream formats are VORBIS, MP3 and THEORA.	Other
	  values will be ignored and cause ezstream to simply pass through the
	  data,	which may or may not work.

     <filename />
	  (Mandatory.) Set the path and	name of	a single media file, a
	  playlist, the	name of	an external program (see below), or the	key-
	  word stdin for streaming from	standard input.	 Playlists are recog-
	  nized	by their filename extension and	end with either	.m3u or	.txt.

	  A playlist consists of filenames, one	entry per line.	 Comments in
	  playlists are	introduced by a	`#' sign at the	beginning of a line
	  and ignored by ezstream.

     <playlist_program />
	  (Optional.) Set to 1 (one) to	indicate that the file in <filename/>
	  is actually an executable program or script.	If set to 0 (zero),
	  <filename/> content is assumed to be a media file, playlist file or
	  the keyword stdin (the default).

	  See the SCRIPTING section for	details	on how the playlist program
	  must behave.

     <shuffle />
	  (Optional.) Set to 1 (one) to	randomly shuffle the entries of	the
	  playlist specified in	<filename/>.  Files are	played sequentially if
	  set to 0 (zero) or when the <shuffle/> element is absent.  This op-
	  tion will be ignored if <playlist_program/> is set to	1 (one.)

     <metadata_progname	/>
	  (Optional.) Set the path and name of an executable program or	script
	  that should be used by ezstream to set the metadata of the stream.
	  The program is automatically queried when a new track	is streamed,
	  or whenever the SIGUSR2 signal is received.

	  If the <metadata_progname/> element is present in the	configuration,
	  no attempts will be made to read metadata from files that are	being
	  streamed.  If	this behavior is not desired, it should	be removed or
	  commented out	in the configuration file.

	  See the SCRIPTING section for	details	on how the metadata program
	  must behave.

     <metadata_format />
	  (Optional.) Set the format of	the string that	should be used for the
	  `@M@'	placeholder when setting metadata with an external program or
	  script via <metadata_progname/>.

	  See the METADATA section for details on how metadata is handled by

     <stream_once />
	  Set to 1 (one) in order to stream the	content	of <filename/> only
	  once,	and to 0 (zero)	for continuous streaming (the default).

     <reconnect_tries />
	  Set how many attempts	should be made to reconnect to the Icecast
	  server in case the connection	is interrupted.	 The default is	to try
	  indefinitely,	which is equal to setting this configuration option to
	  0 (zero).

     <svrinfoname />
	  (Optional.) Set the name of the broadcast.  Informational only.

     <svrinfourl />
	  (Optional.) Set the URL of the web site associated with the broad-
	  cast.	 Informational only.

     <svrinfogenre />
	  (Optional.) Set the genre of the broadcast.  Informational only,
	  used for YP.

     <svrinfodescription />
	  (Optional.) Set the description of the broadcast.  Informational
	  only,	used for YP.

     <svrinfobitrate />
	  (Optional.) Set the bit rate of the broadcast.  This setting is also
	  purely informational and only	used for YP.  The value	is set by the
	  user and not ezstream, and should match the bit rate of the stream.

     <svrinfoquality />
	  (Optional.) Set the quality setting of an Ogg	Vorbis broadcast.  In-
	  formational only and needs to	be set by the user, used for YP.

     <svrinfochannels />
	  (Optional.) Set the number of	audio channels in the broadcast, e.g.
	  1 (one) for mono or 2	for stereo.  Informational only	and needs to
	  be set by the	user, used for YP.

     <svrinfosamplerate	/>
	  (Optional.) Set the sample rate of the broadcast.  Informational
	  only and needs to be set by the user,	used for YP.

     <svrinfopublic />
	  (Optional.) Set to 1 (one) if	the broadcast may be listed in a pub-
	  lic YP directory.  If	set to 0 (zero), the Icecast server will not
	  submit this stream to	a YP directory,	which is also the default if
	  the <svrinfopublic/> element is absent.

     <reencode />
	  (Optional.) Element that contains child elements, which specify if
	  and how re-encoding should be	done.

   Re-encoding settings
     Each of the re-encoding configuration elements have the <reencode/> ele-
     ment as their parent.

     <enable />
	  Set to 1 (one) to enable re-encoding.	 If set	to 0 (zero), no	re-en-
	  coding will be done, which is	also the default if the	<enable/> ele-
	  ment is absent.

     <encdec />
	  Element that contains	child elements,	which specify how to decode
	  and encode a certain media file format for streaming.	 Each format
	  is described by a separate <encdec/> element.

   Decoder/Encoder settings
     Each of the decoder/encoder configuration elements	have the <encdec/> el-
     ement as their parent.

     <format />
	  This element is used by ezstream to find the appropriate encoder for
	  the output stream format specified in	the <format/> element inside
	  the global configuration.  For consistency reasons, it is recom-
	  mended that this element is always supplied, even for	currently un-
	  supported output formats, with content such as VORBIS, MP3, THEORA,
	  FLAC,	et cetera.

     <match />
	  Set the filename extension used to identify a	given media file for-
	  mat.	This allows ezstream to	find the appropriate decoder for a
	  given	file.  Should be set to	.mp3 for MP3, .flac for	FLAC, .ogg for
	  Ogg Vorbis, and so on.

     <decode />
	  Set the command to decode the	specified media	file format to raw
	  data and send	it to standard output.	During runtime,	the place-
	  holder `@T@' is replaced with	the name of the	media file, as it is
	  specified in the <filename/> element or contained in a playlist
	  file.	 It should always be enclosed in quotes, to prevent problems
	  with filenames that contain whitespaces.

	  Metadata placeholders	can be used in the <decode/> element as	well,
	  for combined de-/encoder programs that produce data that can be
	  streamed.  See the METADATA section for details on how metadata is
	  handled by ezstream.

	  For example, to decode Ogg Vorbis files using	the oggdec utility:

		<decode>oggdec -R -o - "@T@"</decode>

     <encode />
	  Set the command to encode raw	data, received from standard input, to
	  the specified	stream format.

	  Metadata placeholders	can be used in the <encode/> element.  For de-
	  tails	about using metadata in	ezstream, see below in the METADATA

	  For example, to encode an Ogg	Vorbis stream using the	quality	set-
	  ting 1.5 with	the oggenc utility:

		<encode>oggenc -r -q 1.5 -t "@M@" -</encode>

     The ezstream 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.

   Common Rules
     -	 The program must be an	executable file.
     -	 The program must write	one line to standard output and	exit.
     -	 The program must not require arbitrary	command	line options to	func-
	 tion.	A wrapper script must be used if there is no other way.

   Playlist Programs
     -	 The program must return only filenames, with one filename per execu-
     -	 The program should not	return an empty	line unless ezstream is	sup-
	 posed to know that the	end of the playlist has	been reached.  This is
	 significant when the <stream_once/> option is enabled.

   Metadata Programs
     -	 The program must not return anything (just a newline character	is
	 okay) if it is	called by ezstream with	a command line parameter that
	 the program does not support.
     -	 When called without command line parameters, the program should re-
	 turn a	complete string	that should be used for	metadata.
     -	 When called with the command line parameter "artist", the program
	 should	return only the	artist information of the metadata.
     -	 When called with the command line parameter "title", the program
	 should	return only the	title information of the metadata.
     -	 The supplied metadata must be encoded in UTF-8.

     The main tool for handling	metadata with ezstream is placeholders in de-
     coder and encoder commands	that are replaced with real content during
     runtime.  The tricky part is that one of the placeholders has to be han-
     dled differently, depending on where the metadata comes from.  This sec-
     tion will explain each possible scenario.

   Metadata Placeholders
     @T@  Replaced with	the media file name.  Required in <decode/> and	is
	  available in <metadata_format/>.

     @M@  Replaced with	a metadata string.  See	below for a detailed explana-
	  tion.	 Available in <decode/>	and <encode/>.

     @a@  Replaced with	the artist information.	 Available in <decode/>,
	  <encode/> and	<metadata_format/>.

     @t@  Replaced with	the title information.	Available in <decode/>,
	  <encode/> and	<metadata_format/>.

     @s@  Replaced with	the string returned by <metadata_progname/> when
	  called without any command line parameters.  Available only in

   The @M@ Placeholder
     While all other placeholders are simply replaced with whatever data they
     are associated with, `@M@'	is context-sensitive.  The logic used by
     ezstream is the following:

	   If ('@M@ is present')
	       If ('<metadata_progname/>' AND '<metadata_format/>')
		   Replace with	format string result.
		   If (NOT '<metadata_progname/>' AND '@t@ is present')
		       Replace with empty string.
		       Replace with generated metadata string.

     The generated metadata string for `@M@' is	of the format "Artist -
     Title", 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 "Artist".	 If neither artist nor title are
     available,	the name of the	media file -- without its file extension -- is

   Metadata Caveats
     It	is possible to generate	strange	results	with odd combinations of
     placeholders, external metadata programs and updates during runtime via
     SIGUSR2.  If things start to become just confusing, simplify.

     Metadata updates during runtime are done with a relatively	broken feature
     of	libshout.  Additional metadata information that	is already present in
     the stream	sent via ezstream is usually destroyed and replaced with the
     new data.	It is not possible to properly discern between artist and ti-
     tle information, which means that anything	set with the SIGUSR2 feature
     will continue to end up entirely in the "Title" field of a	stream.

     Of	all possible Ogg-based streams,	only Ogg Vorbis	can have its metadata
     manipulated by Icecast.  Any attempt of ezstream to update	other Ogg
     metadata is actually a no-op.

     While ezstream tries to do	its best with relaying metadata	accurately to
     Icecast, and subsequently the listeners, different	codesets and locales
     can pose a	problem.  Especially when streaming MP3	files, it may help to
     explicitly	set a codeset to work with via the LC_CTYPE environment	vari-
     able, as ezstream assumes ID3v1 tags to be	in the user's current locale.
     Note that,	even though support for	different locales is provided by
     ezstream, 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 to use the characters available in the ISO-8859-1 codeset.

     External encoders may put additional, and possibly	artificial, restric-
     tions on valid characters in metadata.

     /usr/local/share/examples/ezstream	 Directory containing example configu-
					 ration	files for various uses of
					 ezstream, as well as example playlist
					 and metadata scripts.


     ezstream was written by:

     Ed	Zaleski	<>
     Moritz Grimm <>

     This manual was written by	Moritz Grimm.

ezstream 0.5.6			March 02, 2021			ezstream 0.5.6


Want to link to this manual page? Use this URL:

home | help