[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 ff]
	purpose = jump N seconds forward or backward
	synopsis = n[-]
	aux_info = VSS_READ | VSS_WRITE
	[description]
		This sets the 'R' (reposition request) bit of the vss status flags
		which enqueues a request to jump n seconds forwards or backwards.

		Example:

		     para_client ff 30-

		jumps 30 seconds backwards.

	[/description]

[subcommand help]
	purpose = list available commands or print command-specific help
	non-opts-name = [command]
	aux_info = NO_PERMISSION_REQUIRED
	[description]
		Without any arguments, help prints a list of available commands. When
		called with a command name as first argument, it prints the description
		of this command.
	[/description]

[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]

[subcommand init]
	purpose = initialize the database tables for the audio file selector
	synopsis = [table_name...]
	aux_info = AFS_READ | AFS_WRITE
	[description]
		When invoked without arguments, this command creates all
		tables: audio_files, attributes, scores, moods, lyrics, images,
		playlists. Otherwise only the given tables are created.
	[/description]

[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 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]
		Set the 'P' (playing) bit of the vss status flags.
	[/description]

[subcommand sender]
	purpose = control paraslash senders
	synopsis = [sender cmd [arguments]]
	aux_info = VSS_READ | VSS_WRITE
	[description]
		Send a command to a specific sender. The following commands are
		available, but not all senders support every command.

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

		The help command prints the help text of the given sender. If no
		command is given the list of available senders is shown.

		Example:

			para_client sender http help

	[/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 tasks]
	purpose = list active server tasks
	aux_info = NO_PERMISSION_REQUIRED
	[description]
		For each task, print ID, status and name. This is mostly useful
		for debugging.
	[/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 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