path: root/m4/lls/server_cmd.suite.m4

[suite server_cmd]
caption = list of server commands
aux_info_prefix = Permissions:

[introduction]
	The server process listens on a network socket and accepts connections
	from para_client or para_audiod. For the connection to succeed the
	connecting peer must authenticate as one of the users stored in the
	user table of para_server. Each entry of the user table contains the
	set of permission bits that are granted to the user. Authenticated
	users may execute one of the commands below if the set of permission
	bits of the command is a subset of the permission bits that are
	granted to the user.
[/introduction]

[subcommand add]
	purpose = add or update audio files
	non-opts-name = path...
	aux_info = AFS_READ | AFS_WRITE
	[description]
		Each path must be absolute and refer to either an audio file or a
		directory. In case of a directory, all audio files in that directory
		are added recursively. Note that the given paths refer to files or
		directories on the host on which para_server is running.
	[/description]
	[option all]
		short_opt = a
		summary = add all files
		[help]
			The default is to add only files ending in a known suffix for a
			supported audio format.
		[/help]
	[option lazy]
		short_opt = l
		summary = add files lazily
		[help]
			If the path already exists in the database, skip this file. This
			operation is really cheap. Useful to update large directories after
			some files have been added.
		[/help]
	[option force]
		short_opt = f
		summary = force adding/updating
		[help]
			Recompute the audio format handler data even if a file with the same
			path and the same hash value exists.
		[/help]
	[option verbose]
		short_opt = v
		summary = enable verbose mode
		[help]
			Print what is being done.
		[/help]

[subcommand addatt]
	purpose = add new attribute(s)
	non-opts-name = attribute...
	aux_info = AFS_READ | AFS_WRITE
	[description]
		This adds new attributes to the attribute table. At most 64 attributes
		may be defined.
	[/description]

[subcommand check]
	purpose = run integrity checks on database tables
	aux_info = AFS_READ
	[description]
		If no options are given, all checks are run.
	[/description]
	[option aft]
		short_opt = a
		summary = run audio file table checks
		[help]
			Report stale paths and invalid image and lyrics ids of the audio
			file table.
		[/help]
	[option attribute]
		short_opt = A
		summary = deprecated, has no effect, will be removed, so don't use
	[option mood]
		short_opt = m
		summary = check for invalid mood definitions
		[help]
			Run syntax checks on all moods of the mood table.
		[/help]
	[option playlist]
		short_opt = p
		summary = find invalid paths in playlists
		[help]
			Check all playlists for paths not contained in the audio file table.
		[/help]

[subcommand cpsi]
	purpose = copy selected parts of the audio file selector info
	non-opts-name = source pattern...
	aux_info = AFS_READ | AFS_WRITE
	[description]
		If no option, or only --verbose is given, all fields of the audio
		file selector info structure are copied to each row of the audio file
		table whose path matches at least one of the given patterns. Otherwise,
		only those fields which correspond to the given options are copied.
	[/description]
	[option attribute-bitmap]
		short_opt = a
		summary = copy the attribute bitmap
	[option image-id]
		short_opt = i
		summary = copy the image id
	[option lyrics-id]
		short_opt = y
		summary = copy the lyrics id
	[option lastplayed]
		short_opt = l
		summary = copy the lastplayed timestamp
	[option numplayed]
		short_opt = n
		summary = copy the numplayed counter
	[option verbose]
		short_opt = v
		summary = enable verbose mode

[subcommand ff]
	purpose = jump forward or backward in the current audio file
	synopsis = seconds
	aux_info = VSS_READ | VSS_WRITE
	[description]
		This enqueues a request to reposition the audio stream according to
		the argument, which may be a signed or an unsigned integer. Negative
		values correspond to backward jumps.

		If a negative number is given whose absolute value exceeds the current
		postition of the stream, a jump to the beginning of the audio file
		is performed. If a positive amount of seconds is given which exceeds
		the remaining time of the audio file, the next audio file is loaded.

	[/description]

[subcommand help]
	purpose = list available commands or print command-specific help
	non-opts-name = [command]
	aux_info = NO_PERMISSION_REQUIRED
	[description]
		When executed without any arguments, the available server commands
		are listed. Otherwise, if the first argument is the name of a server
		command, the description of this command is shown.
	[/description]
	m4_include(`long-help.m4')

[subcommand hup]
	purpose = reload config file, log file and user list
	aux_info = VSS_WRITE
	[description]
		Reread the config file and the user list file, close and reopen the log
		file, and ask the afs process to do the same. Sending the HUP signal
		to the server process has the same effect as running this command.
	[/description]

m4_include(`com_ll.m4')

[subcommand jmp]
	purpose = reposition the current stream
	non-opts-name = n
	aux_info = VSS_READ | VSS_WRITE
	[description]
		Set the 'R' (reposition request) bit of the vss status flags and
		enqueue a request to jump to n% of the current audio file, where 0 <=
		n <= 100.
	[/description]

[subcommand ls]
	purpose = list audio files which match a pattern
	non-opts-name = [pattern...]
	aux_info = AFS_READ
	[description]
		If no pattern is given, all files are listed.  Otherwise, the command
		lists all files of the audio file table whose path matches at least
		one of the given patterns.
	[/description]
	[option listing-mode]
		short_opt = l
		summary = use alternative output format
		arg_type = string
		arg_info = optional_arg
		typestr = mode
		default_val = long
		[help]
			The optional mode argument is either a single character or a word
			according to the following list.

			short (s). List only the path or basename (last component of the path),
			depending on whether -p is also given. This listing mode acts as if
			--listing-mode had not been given.

			long (l). Show detailed information. This is the default if no argument
			to --listing-mode is supplied.

			verbose (v). Multi-line output, one row per data field stored in the
			audio file table.

			parser-friendly (p). Like verbose listing mode, but use numerical
			values for the names of the output fields and prefix each line with
			a length field.
		[/help]
	[option limit]
		short_opt = L
		summary = list at most this many files
		arg_type = uint32
		arg_info = required_arg
		typestr = num
		[help]
			An argument of zero means "unlimited". This is also the default which
			applies if the option is not given.
		[/help]
	[option basename]
		short_opt = b
		summary = list and match basenames only
		[help]
			Print only the basename of each matching file and match only the
			basenames of the paths stored in the audio file table against the
			given patterns. The default is to print and match the full path.
		[/help]
	[option admissible]
		short_opt = a
		summary = list only admissible files
		arg_type = string
		arg_info = optional_arg
		typestr = specifier/name
		default_val = .
		[help]
			If the optional argument is supplied, it must be of the form "p/foo"
			or "m/bar" (which refer to the playlist named "foo" and the mood named
			"bar", respectively). The command then restricts its output to the set
			of files which are admissible with respect to the thusly identified
			mood or playlist.

			If no argument is given, or if the argument is the special value ".",
			the current mood or playlist is assumed.
		[/help]
	[option reverse]
		short_opt = r
		summary = reverse sort order
	[option unix-date]
		short_opt = d
		summary = print dates as seconds after the epoch
	[option sort]
		short_opt = s
		summary = change sort order
		arg_type = string
		arg_info = required_arg
		typestr = order
		default_val = path
		[help]
			The sort order must be given as an required argument. Like for
			--listing-mode, this argument may either be a single character or a
			word, according to the following list.

			path (p). Sort alphabetically by path or basename, depending on
			whether -b is given. This is the default if --sort is not given.

			score (s). Iterate over the entries of the score table, rather than
			the audio file table. This sort order implies --admissible, since
			the score table contains only admissible files.

			lastplayed (l)

			numplayed (n)

			frequency (f)

			channels (c)

			image-id (i)

			lyrics-id (y)

			bitrate (b)

			duration (d)

			audio-format (a)

			hash (h)

			If --sort is not given, path sort is implied.
		[/help]

[subcommand lsatt]
	purpose = list attributes
	aux_info = AFS_READ
	non-opts-name = pattern...
	[description]
		Print the list of all defined attributes which match the given
		pattern. If no pattern is given, the full list is printed.
	[/description]

	[option id-sort]
		short_opt = i
		summary = sort attributes by id
		[help]
			The default is to sort alphabetically by name.

			Attributes are internally represented as an 64 bit array. The attribute
			id is the bit number in this array.
		[/help]
	[option long]
		short_opt = l
		summary = print long listing
		[help]
			The long listing prints the attribute id in addition to the name of
			the attribute. The id is printed as a decimal number and is separated
			from the name by a tab character.
		[/help]
	[option reverse]
		short_opt = r
		summary = reverse sort order

[subcommand mvatt]
	purpose = rename an attribute
	synopsis = source dest
	aux_info = AFS_READ | AFS_WRITE
	[description]
		Rename the attribute given by the first argument to the destination
		given by the second argument. It is an error if the destination
		attribute exists.
	[/description]

[subcommand next]
	purpose = close the stream and start to stream the next audio file
	aux_info = VSS_READ | VSS_WRITE
	[description]
		Set the 'N' (next audio file) bit of the vss status flags. This
		instructs the server to close the current stream, if any. The 'P'
		(playing) bit is not modified by this command. If it is on, playing
		continues with the next audio file.

		This command is equivalent to stop if paused, and has no effect
		if stopped.
	[/description]

[subcommand nomore]
	purpose = stop playing after current audio file
	aux_info = VSS_READ | VSS_WRITE
	[description]
		Set the 'O' (no more) bit of the vss status flags which asks
		para_server to clear the 'P' (playing) bit after the 'N' (next audio
		file) bit transitions from off to on (because the end of the current
		audio file is reached). Use this command instead of stop if you don't
		like sudden endings.
	[/description]

[subcommand pause]
	purpose = suspend the current stream
	aux_info = VSS_READ | VSS_WRITE
	[description]
		Clear the 'P' (playing) bit of the vss status flags.
	[/description]

[subcommand play]
	purpose = start or resume playback
	aux_info = VSS_READ | VSS_WRITE
	[description]
		This operates on the status flags of the virtual streaming system as follows:
		Set the 'P' (playing) flag, clear the 'O' (nomore) flag, then check the
		value of the 'N' (next) flag. If it is set. open the next audio file and
		stream it. Otherwise, continue to stream the current file.
	[/description]
	[option next]
		short_opt = n
		summary = switch to the next file
		[help]
			This sets the 'N' (next) flag in addition to the 'P' flag. Equivalent to
			executing "next", then "play".
		[/help]

[subcommand rm]
	purpose = remove rows from the audio file table
	non-opts-name = pattern...
	aux_info = AFS_READ | AFS_WRITE
	[description]
		Remove all rows of the audio file table which match any of the given
		patterns. Note that this affects only the database table; the command
		won't touch your audio files on disk.
	[/description]
	[option verbose]
		short_opt = v
		summary = print paths of deleted rows
	[option force]
		short_opt = f
		summary = don't complain if nothing was removed
	[option pathname-match]
		short_opt = p
		summary = modify matching behaviour
		[help]
			Match a slash in the path only with a slash in pattern and not by an
			asterisk (*) or a question mark (?) metacharacter, nor by a bracket
			expression ([]) containing a slash (see fnmatch(3)).
		[/help]

[subcommand rmatt]
	purpose = remove attribute(s)
	non-opts-name = pattern...
	aux_info = AFS_READ | AFS_WRITE
	[description]
		Remove all attributes which match any given pattern. All information
		about the removed attributes in the audio file table is lost.
	[/description]

[subcommand select]
	purpose = activate a mood or a playlist
	non-opts-name = mop
	aux_info = AFS_READ | AFS_WRITE
	[description]
		The argument is either a special string or a string of the form
		"specifier/name", where the specifier is either "m" or "p" to indicate
		whether a playlist or a mood should be activated. For example, "select m/foo"
		activates the mood "foo".

		The following two special strings are supported: "-" activates the previous
		mood or playlist, and "." reloads the current mood or playlist, recomputing
		the score of each admissible file.
	[/description]
	[option verbose]
		short_opt = v
		summary = print information about the loaded mood or playlist

[subcommand sender]
	purpose = control paraslash senders
	synopsis = [sender subcmd [arguments]]
	aux_info = VSS_READ | VSS_WRITE
	[description]
		This command executes a subcommand for the given sender, which is either
		"http" or "udp". Various subcommands exist to print information about the
		sender, to activate and deactivate the sender, and to change the access
		permissions and targets. The following subcommands are available:

		       help, status, on, off, allow, deny, add, delete.

		All senders support the first four commands. The "allow" and "deny" commands
		are only supported by the http sender while "add" and "delete" are only
		supported by the udp sender. If no sender is given, the list of available
		senders is shown.

		Examples:

		Get help for the udp sender (contains further examples):

			sender udp help

		Show the access control list and the number of connected clients of
		the http sender:

			sender http status

		Senders may be activated and deactivated independently of each
		other. The following command switches off the http sender:

			sender http off

		Add an UDP unicast for a client to the target list of the UDP sender:

			sender udp add client.foo.org

		Start UDP multicast, using the default multicast address:

			sender udp add 224.0.1.38

	[/description]

[subcommand si]
	purpose = print server info
	aux_info = NO_PERMISSION_REQUIRED
	[description]
		Show server and afs PID, number of connections, uptime and more.
	[/description]

[subcommand stat]
	purpose = print information about the current audio file
	aux_info = VSS_READ
	[option num]
		short_opt = n
		summary = number of times to show the status info
		arg_info = required_arg
		arg_type = uint32
		typestr = num
		[help]
			Exit after the status information has been shown num times. If this
			option is not given, the command runs in an endless loop.
		[/help]
	[option parser-friendly]
		short_opt = p
		summary = enable parser-friendly output
		[help]
			Show status item identifiers as numerical values and prefix each
			status item with its size in bytes.
		[/help]

[subcommand stop]
	purpose = stop playback
	aux_info = VSS_READ | VSS_WRITE
	[description]
		Clear the 'P' (playing) bit and set the 'N' (next audio file) bit of
		the vss status flags, effectively stopping playback.
	[/description]

[subcommand term]
	purpose = ask the server to terminate
	aux_info = VSS_READ | VSS_WRITE
	[description]
		Shut down the server. Instead of this command, you can also send
		SIGINT or SIGTERM to the para_server process. It should never be
		necessary to send SIGKILL.
	[/description]

[subcommand touch]
	purpose = manipulate the afs information of audio files
	non-opts-name = pattern...
	aux_info = AFS_READ | AFS_WRITE
	[description]
		This command modifies the afs info structure of all rows of the audio
		file table whose path matches at least one of the given patters.

		If one or more options which affect the afs information are given, only
		the corresponding fields of the afs info structure are updated. All other
		fields stay unmodified. For example, "touch --numplayed=42" only modifies
		the numplayed field.

		If no such option is given, the lastplayed field is set to the current
		time and the value of the numplayed field is increased by one while
		all other fields are left unchanged. This mimics what happens when
		the virtual streaming system selects the file for streaming.

		If the file is admissible for the current mood, its score is recomputed.
	[/description]
	[option numplayed]
		short_opt = n
		summary = set the numplayed count manually
		arg_type = uint32
		arg_info = required_arg
		typestr = num
		[help]
			The numplayed count of an audio file is the number of times the file
			was selected for streaming. It is one of the inputs to the scoring
			function which determines the order in which admissible files are
			streamed.

			The virtual streaming system increases this number automatically each
			time it opens the file for streaming.
		[/help]
	[option lastplayed]
		short_opt = l
		summary = set the lastplayed time manually
		arg_type = uint64
		arg_info = required_arg
		typestr = num
		[help]
			The lastplayed time of an audio file is the time when the file was
			last opened for streaming.

			Like the numplayed count, it is an input for the scoring function
			and is updated automatically by the virtual streaming system.

			The argument must be a number of seconds since the epoch. Example:

				touch -l=$(date +%s) file

			sets the lastplayed time of 'file' to the current time.
		[/help]
	[option image-id]
		short_opt = i
		summary = set the image id
		arg_type = uint32
		arg_info = required_arg
		typestr = num
		[help]
			The afs info structure of each row of the audio file table contains
			a slot for the image id of the audio file that corresponds to the
			row. The image id stored in this slot refers to the key in the image
			table that identifies the blob.

			When a new audio file is added to the audio file table, its image
			id starts out as zero, indicating that there is no image associated
			with the file. Setting the image id to a non-zero number associates
			the file with a particular blob of the image table, for example the
			cover art of the album in jpg format.
		[/help]
	[option lyrics-id]
		short_opt = y
		summary = set the lyrics id
		arg_type = uint32
		arg_info = required_arg
		typestr = num
		[help]
			This option works just like --image-id, but sets the lyrics ID rather
			than the image id.
		[/help]
	[option amp]
		short_opt = a
		summary = set the amplification value (0-255)
		arg_type = uint32
		arg_info = required_arg
		typestr = num
		[help]
			The amplification value of an audio file is a number which is stored
			in the afs info structure.

			The value determines the scaling factor by which the amplitude of
			the decoded samples should be multiplied in order to normalize the
			volume. A value of zero means no amplification, 64 means the amplitude
			should be multiplied by a factor of two, 128 by three and so on.

			The amp filter of para_audiod amplifies the volume according to
			this value.
		[/help]
	[option set-attribute]
		short_opt = s
		summary = turn on a bit in the attribute bitmask of each matching file
		arg_type = string
		arg_info = required_arg
		typestr = attr
		default_val = none
		flag multiple
		[help]
			May be given more than once to set multiple attributes in one invocation.
		[/help]
	[option unset-attribute]
		short_opt = u
		summary = turn off a bit in the attribute bitmask of each matching file
		arg_type = string
		arg_info = required_arg
		typestr = attribute
		default_val = none
		flag multiple
		[help]
			Like --set-attribute, this may be given multiple times.
		[/help]
	[option verbose]
		short_opt = v
		summary = explain what is being done
	[option dry-run]
		summary = do not store the modified afs information
	[option pathname-match]
		short_opt = p
		summary = modify matching behaviour
		[help]
			Match a slash in the path only with a slash in pattern and not by an
			asterisk (*) or a question mark (?) metacharacter, nor by a bracket
			expression ([]) containing a slash (see fnmatch(3)).
		[/help]

[subcommand version]
	purpose = print the git version string of para_server
	aux_info = NO_PERMISSION_REQUIRED
	[option verbose]
		short_opt = v
		summary = print detailed (multi-line) version text

m4_define(`BLOB_COMMANDS', `
[subcommand rm`$2']
	purpose = remove `$1' blob(s)
	non-opts-name = pattern...
	aux_info = AFS_READ | AFS_WRITE
	[description]
		Remove all `$1' blobs which match any of the given patterns.
	[/description]

[subcommand mv`$2']
	purpose = rename `$1' blob(s)
	non-opts-name = source dest
	aux_info = AFS_READ | AFS_WRITE
	[description]
		Rename `$1' source to dest. The command fails if the source `$1'
		does not exist or if the destination `$1' already exists.
	[/description]

[subcommand add`$2']
	purpose = add a blob to the `$1' table
	non-opts-name = `$1'_name
	aux_info = AFS_READ | AFS_WRITE
	[description]
		Read from stdin and ask the audio file selector to create a blob in
		the `$1' table. If the named blob already exists, it gets replaced
		with the new data.
	[/description]

[subcommand cat`$2']
	purpose = dump a `$1' blob to stdout
	non-opts-name = `$1'_name
	aux_info = AFS_READ

[subcommand ls`$2']
	purpose = list blobs of type `$1' which match a pattern
	non-opts-name = [pattern...]
	aux_info = AFS_READ
	[description]
		Print the list of all blobs which match the given pattern. If no
		pattern is given, the full list is printed.
	[/description]
	[option id-sort]
		short_opt = i
		summary = sort by identifier
		[help]
			The default is to sort alphabetically by name.
		[/help]
	[option long]
		short_opt = l
		summary = long listing
		[help]
			Print identifier and name. The default is to print only the name.
		[/help]
	[option reverse]
		short_opt = r
		summary = reverse sort order
')

BLOB_COMMANDS(`moods', `mood')
BLOB_COMMANDS(`playlist', `pl')
BLOB_COMMANDS(`image', `img')
BLOB_COMMANDS(`lyrics', `lyr')