Installing PlayShell
To install PlayShell, run bash install.sh as root, or use sudo: sudo bash install.sh.
You can also use make install or sudo make install.
Running PlayShell
After installing PlayShell, you can run it with playshell.
Running PlayShell Without Installing It
PlayShell can also run in the directory where it was extracted by running bash start.sh. All data and runtime files will be stored in the users directory of the directory where it was extracted.
Command-line Usage
playshell [options] [--] [file | dir, ...]
When playshell is invoked with a file argument, the file gets added at startup, and then played. If it’s a directory, all valid media files in that directory would recursively be added in order, and the first added file would be played.
See options.
Using PlayShell
Quick Reference
In PlayShell’s main prompt, you can get a quick reference of commands that can be used by pressing h (for one-key commands), or typing :help (for long commands). See one-key commands and long commands.
Also when you’re on a command’s prompt, you can enter ? to get a brief information about the command and the form of arguments it accepts.
Media Files Library
The library is an optional list of files that can be used for keyword searching. It is generated based on a list of directories (paths list) which is generally located in the file ~/.playshell/paths (or users/${USER}/paths if not installed).
You can modify the paths list and add directories to it with the command edit_paths (E). This would open an editor based on the value of $EDITOR. From here you would enter the complete path of each directory that you would like to add. All media files in those directories that end in extensions specified in exts.table will be added recursively.
After making changes to the file and exiting the editor, the library will be automatically regenerated. You can also manually refresh it with the command refresh_lib (F).
Adding Entries to PlayList
To add a new entry in the playlist, you can use the commands add (a), add_and_play (A), or play (enter). In a command’s prompt you can specify a path, a glob pattern, a special argument, or a set of keywords. You can use tab-based completion to make it easier for you to add file paths. You can also use up and down arrow keys to scan through history of entered lines.
If you specify a directory, all valid media files in that directory would be added.
If you specify a glob pattern, it would expand to files and directories and all valid media files in it would be added.
If you specify a special argument, an entry would be added from the library based on its meaning or purpose. For example, to add all entries in the library you can use *, @a or @all.
Keyword Negation
PlayShell recognizes negation in keywords through the use of exclamation point (!). Negation allows the user to find entries that would instead not match an expression. If a user enters ! followed with a space, everything after it is negated. If ! sits directly in front of a keyword and no space is placed between them, only that specific keyword gets negated. Double-negation would also apply.
Playing a Playlist Entry
To play an entry in the playlist, you can use play @current (x), or play @first_of_latests (X). You can also use select (space) while playing to play another.
Adding and Playing at the Same Time
You can use add_and_play (A), or play (enter) to add and play an entry at the same time. The difference between those two is that play (enter) is also capable of playing entries in the playlist, and keyword searchng matches the entries in the playlist first and then the library if nothing was found. Keyword matching with add_and_play (A) only targets the library.
Shuffling
Play shuffling can be enabled or disabled by the command shuffle (u). PlayShell’s shuffling system is pool-based. That is, at the start of a shuffling session (when shuffling is enabled), all entries are placed on a shuffling pool. Everytime a new entry is played for the next track, a random entry is taken from the pool. When the pool gets empty, all entries are returned to it, in which case starts a new session. In addition, all newly added entries are added to the pool as well. This ensures that all entries are played before one gets played again for the second time.
This mode is affected by repeat mode, loop mode, manual mode. Entries in queue are also prioritized before this.
Repeating
Repeating of a playlist is enabled by the command repeat (r). Playing would go back to the first entry after playing the last entry in the playlist if this is enabled.
When shuffling is enabled and this is also enabled, a new shuffling session follows when all the entries in the shuffling pool becomes empty, otherwise play would stop.
This mode is affected by loop mode, and manual mode.
Looping
Looping is enabled by the command loop (o). If loop mode is enabled, and manual mode is not enabled, repeating, shuffling and queuing are ignored, and PlayShell repeats the current entry after it stops playing.
This mode is affected by manual mode.
Manual Mode
Manual mode is enabled by the command manual (@). When this mode is enabled, playing would always stop at the current entry unless an entry is in queue. Queuing is also considered as a manual action that is why it was decided that manual mode would not override it.
Queuing
Queuing allows a user to prioritize a specific entry to play next after the current playing entry. It can be done using queue (N) (appends), or requeue (N) (overrides).
Disabling Video Output
Some media players like MPlayer, VLC, and FFplay allow media to be played without having to show video output, and this can be configured in PlayShell using the command video (^). If video output is disabled, and the player supports it, video would no longer be shown on the next entry that would be played.
Pause Between Plays
PlayShell also has a feature that allows you to have pauses between plays. This could make adjacent tracks sound less repetitive, and could prevent you from memorizing the start of a track after another track ends. Music will also be played in a more random or less expected manner, or less recognizable pattern.
The command for this is interval (#). You can specify a single integer or a range. The range is in the form of n-m (e.g. 5-15) where intervals would be randomly selected from n to m on every instance.
Configuration
Please see playshell.conf.example for information on how to set-up default configurations for PlayShell.
You can also run playshell with -h or --help to get information on how to configure PlayShell with extra arguments or options.
See current playshell.conf.example.
Changing the Default Editor
The recommended way is to have a configuration file playshell.conf and specify the editor there (see playshell.conf.example).
You can also temporarily use a different edtor by using the option --editor (see playshell --help).
You can also change the value of the global variable EDITOR. This variable is referenced by most programs when knowing what editor is used by the system by default. In most systems this can be changed system wide by changing its value in rc configuration files or scripts.
Last thing is you can change the values in source/defaults.sh. If you run PlayShell in installed mode, you should reinstall it again.
Configuring Players
Among the players detected, one is chosen to play an entry based on the filename’s extension and the order in which those players are selected. These configurations are specified in players.table.
Mainly, the players supported by default for using as backend are SoX, VLC, MPlayer and FFplay. Other players like amp, aplay, gst123, madplay, mpg321, mpg123 and splay are also supported.
Custom support for players can also be added by modifying /etc/playshell/tables/players.table or having a modified copy of it as ~/.playshell/players.table. If PlayShell is not being run as installed, the files to modify are tables/players.table or users/${USER}/players.table respectively.
See current players.table.
Files
The following are configuration files used by PlayShell when installed:
/etc/playshell/playshell.conf
– PlayShell’s configuration file.~/.playshell/playshell.conf
– PlayShell’s user-specific configuration file. It overrides values provided in/etc/playshell/playshell.conf./etc/playshell/playshell.conf.example
– An example configuration file./etc/playshell/tables/players.table,~/.playshell/players.table
– Contains data of media players that can be used by PlayShell./etc/playshell/tables/exts.table,/.playshell/exts.table
– Contains data of media file extensions.