Paraslash Audio Streaming
	About   News   Download   Documentation   Development

para_play

para_play - command line audio player

para_play [--help] [--detailed-help] [--version] [--loglevel=<severity>] [--config-file=<filename>] [--history-file=<filename>] [--randomize] [--end-of-playlist=<behaviour>] [--key-map=<key:command [args]>] [--] <audio_file>...

para_play operates either in command mode or in insert mode. In insert mode it presents a prompt and allows the user to enter commands like play, pause, quit, etc. In command mode the current audio file and the playback position are shown instead of the prompt/command line, and the program reads single key strokes from stdin. Keys may be mapped to commands so that the configured command is executed whenever a mapped key is pressed.

Common options
The following options are implemented generically and are available for many of the commands.
-h, --help

print help and exit

--detailed-help

print help, including all details, and exit

-V, --version

print version and exit

-l, --loglevel=<severity>

control amount of logging

values: debug, info, notice, warning, error, crit, emerg

Log only messages with severity greater or equal than the given value. Possible values:

debug: Produces really noisy output. info: Still noisy, but won’t fill up the disk quickly. notice: Indicates normal, but significant event. warning: Unexpected events that can be handled. error: Unhandled error condition. crit: System might be unreliable. emerg: Last message before exit.

-c, --config-file=<filename>

path to alternative config file

default: ~/.paraslash/play.conf

para_play reads its config file right after parsing the options that were given at the command line. If an option is given both at the command line and in the config file, the value that was specified at the command line takes precedence.

--history-file=<filename>

location of the file for the command history list

If para_play runs in interactive mode, it reads the history file on startup. Upon exit, the in-memory history is appended to the history file.

If this option is not given, the history file is expected at ~/.paraslash/play.history.

Options for para_play
-z, --randomize

randomize playlist at startup

--end-of-playlist=<behaviour>

what to do after the last file has been played

values: loop, stop, quit

-k, --key-map=<key:command [args]>

map a key to a command

This option may be given multiple times, one for each key mapping. Example:

--key-map 5:jmp 50

help - list commands or keybindings, or print command-specific help
Usage: help [--long] [--] [command]

This command acts differently depending on whether it is executed in command mode or in insert mode.

In command mode, the help command prints the list of defined keybindings. In insert mode, if no argument is given, it prints the list of available commands. When called with the name of a command as first argument, it prints the description of this command.
-l, --long

show the long help text

If no non-option argument is supplied to the help subcommand and --long is not given, only the names of all subcommands are shown. With --long the purpose of each command is printed as well.

If the name of a subcommand is supplied and --long is given, the help text for the given subcommand contains the synopsis, the purpose and the description of the specified command, followed by the option list including summary and help text of each option. Without --long the description of the command and the option help are omitted.

fg - enter command mode
Usage: fg

In this mode, file name and play time of the current audio file are displayed. Hit CTRL+C or : to switch to input mode.

next - load the next file of the playlist
Usage: next

prev - load the previous file of the playlist
Usage: prev

bg - enter insert mode
Usage: bg

Only useful if called in command mode via a key binding. The default key bindings map the colon key to this command, so pressing : in command mode activates insert mode.

jmp - change playback position
Usage: jmp percent

The percent argument must be an integer between 0 and 100, inclusively.

ff - set playback position relative to the current position
Usage: ff seconds

Negative values mean to jump backwards the given amount of seconds.

ls - list the playlist
Usage: ls

This prints all paths of the playlist. The currently active file is marked with an asterisk.

info - print information about the current file
Usage: info

The output contains the playlist position, the path and information provided by the audio format handler.

play - start or resume playback
Usage: play [num]

If no argument is given, playback starts at the current position. Otherwise, the corresponding file is loaded and playback is started at the beginning of the file.

pause - suspend playback
Usage: pause

When paused, it is still possible to jump around in the file via the jmp and ff commands.

tasks - print list of active tasks
Usage: tasks

Mainly useful for debugging.

quit - exit para_play
Usage: quit

Pressing CTRL+D causes EOF on stdin which also exits para_play.

Written by Andre Noll
Copyright (C) 2024 Andre Noll
License: GNU GPL version 2
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Report bugs to Andre Noll