.TH HTTP-MUSIC-PLAY 1 .SH NAME http-music-play - plays audio from a playlist file .SH SYNOPSIS .B http-music play [opts...] .SH DESCRIPTION Plays audio referenced from a playlist file. Tracks selected using a "picker" (see \fB--picker\fR) and retrieved using a "downloader" (see \fB--downloader\fR). Downloaded tracks are played with either the \fBmpv\fR (default) or \fBplay\fR (from SoX) command. .SH KEYBOARD CONTROLS .TP .BR Skips backwards 5 seconds in the currently playing track; hold shift to skip by 30 seconds. (Requires MPV player.) .TP .BR Skips forwards 5 seconds in the currently playing track; hold shift to skip by 30 seconds. (Requires MPV player.) .TP .BR Skips to the track that just previously played. (\fBp\fR (for "Previous") also works.) .TP .BR Skips past the track that's currently playing. (\fBs\fR (for "Skip") also works.) .TP .BR - Turns the volume up a 10%-notch. Unfortunately, at present, the volume setting is NOT kept across tracks. You'll need to adjust your audio volume whenever a new song starts. (If possible, it might be better just to opt for changing the system volume.) (Requires MPV player.) .TP .BR - Turns the volume down 10%. (Requires MPV player.) .TP .BR Pauses (or resumes) playback. (Requires MPV player.) .TP .BR i Shows information (title, URL/path) about the currently playing track, as well as the upcoming and previously-played three tracks. (Use \fBt\fR to see information about just the current track.) .TP .BR p Skips to the track that just previously played. (\fB\fR also works.) .TP .BR q Quits the http-music process and stops music currently being played. (\fB^C\fR and \fB^D\fR also work.) .TP .BR s Skips past the track that's currently playing. (\fB\fR also works.) .TP .BR t Shows information about the track that's currently playing. (Use \fBi\fR to also see previous and upcoming tracks.) .SH OPTIONS .TP .BR \-c ", " \-\-clear Clears the active playlist. This does not effect the source playlist, so specific groups can be selected using \fB\-\-keep\fR. .TP .BR \-\-collapse\-groups ", " \-\-collapse Collapses groups in the active playlist so that there is only one level of sub-groups. Handy for shuffling the order groups play in; try \fB\-\-collapse-groups \-\-sort shuffle\-groups\fR. .TP .BR \-\-converter Sets the program used for converting tracks. By default the program is either \fBffmpeg\fR or \fBavconv\fR. Playlists which use track-specific converter options should use this option through the \fB"options"\fR playlist property to set an intended converter program. If the program specified through \-\-converter does not exist, converter options will not be used (see \fB\-\-enable\-converter\-options\fR). .TP .BR \-\-disable\-converter\-options ", " \-\-no\-use\-converter\-options Forces track-specific converter options to not be used. See also \fB\-\-enable\-converter\-options\fR. .TP .BR \-\-disable\-playback\-status ", " \-\-hide\-playback\-status Hides playback status (timestamps, etc). .TP .BR \-\-enable\-converter\-options ", " \-\-use\-converter\-options Forces usage of track-specific converter options. By default, they are enabled. See also \fB\-\-disable\-converter\-options\fR. .TP .BR \-f ", " \-\-filter " \fIfilterJSON\fR Filters the playlist so that only tracks that match the given filter are kept. \fIfilterJSON\fR should be a JSON object as described in the section \fBFILTERS\fR. .TP .BR \-h ", " \-? ", " \-\-help Presents a help message, directing the user to the \fBman\fR page. If this is the last option used, nothing plays (see \fB\-\-play\fR). .TP .BR \-k ", " \-\-keep " \fIgroupPath\fR" Keeps a group by adding it from the source playlist. This is usually useful after clearing the active playlist (\fB\-\-clear\fR); it can also be used to keep a sub-group after removing an entire parent group, e.g. \fB-r foo -k foo/baz\fR. .TP .BR \-l ", " \-\-list\-groups ", " \-\-list Lists all groups (but not tracks) in the (active) playlist. If this is the last option used, nothing plays (see \fB\-\-play\fR). .TP .BR \-L ", " \-\-list\-all ", " \-\-list\-tracks Lists all groups and tracks in the (active) playlist. If this is the last option used, nothing plays (see \fB\-\-play\fR). .TP .BR \-\-loop\-mode ", " \-\-loop Sets the mode by which the playback order list is looped (typically, what happens when the picker's index counter gets to the end of the list). Valid options include \fBno-loop\fR (or \fBno\fR), \fBloop-same-order\fR (or \fBloop\fR), and \fBloop-regenerate\fR (the default). See also \fB\-\-sort\-mode\fR. .TP .BR \-np ", " \-\-no\-play Forces the playlist not to play. See also \fB\-\-play\fR. .TP .BR \-o ", " \-\-open\-playlist ", " \-\-open " \fIplaylistFile\fR" Opens a specific file to be used as the playlist file. (This sets the source playlist.) The default playlist file used upon loading is \fBplaylist.json\fR (in the same directory as \fBhttp-music\fR is being run in). .TP .BR \-\-open\-playlist\-string ", " \-\-playlist\-string " \fIplaylistString\fR" Loads a playlist directly from the passed string, which should be the JSON text of a playlist. (This sets the source playlist.) .TP .BR \-p ", " \-\-play Forces the playlist to actually play, regardless of options such as \fB\-\-list\fR. See also \fB\-\-no\-play\fR. .TP .BR \-\-player " \fIplayer" Selects the mode by which audio is played. Valid options include "mpv" and "sox" (or "play"). Most playback controls only work with the "mpv" player, but the "sox"/"play" player is typically much more easy to (and commonly) install than "mpv". The default is \fBmpv\fR, but \fBsox\fR will be used if mpv is not installed. .TP .BR \-\-print\-playlist ", " \-\-log-playlist ", " \-\-json Prints the JSON representation of the active playlist to the console. .TP .BR \-r ", " \-\-remove ", " \-x " \fIgroupPath\fR" Removes a group from the (active) playlist. .TP .BR \-\-show\-keybindings ", " \-\-list\-keybindings Shows the list of keybindings set. Higher items are more prioritized; if A was first bound to showTrackInfo, then later bound to togglePause, pressing A will run togglePause, not showTrackInfo. A: togglePause will also show up higher in the list than A: showTrackInfo, so that it is apparent that it will run togglePause and not showTrackInfo. .TP .BR \-\-status\-line " \fIstring\fR" Sets how the playback status line should appear. See the \fBSTATUS LINES\fR section for information on how to format this string. (As a brief example: \fB--status-line '%name (-%timeLeft%)'\fR will make the status line show up as something along the lines of \fB02 United Colors of Scrapyard (-02:58)\fR.) .TP .BR \-\-sort\-mode ", " \-\-sort Sets the mode by which the playback order list is sorted. Valid options include \fBorder\fR, \fBshuffle\fR (the default), \fBshuffle-groups\fR, and \fBalphabet\fR. (Some variations of these strings, such as \fBa-z\fR and \fBshuffled\fR, are also valid.) See also \fB\-\-loop\-mode\fR. .TP .BR \-s ", " \-\-start ", " \-\-start(ing)-(on|at|track) Sets the track to begin playback from. Especially useful when using an ordered sort; for example, this option could be used to start a long album part way through. (See also \fB\-\-sort\fR.) .TP .BR \-\-track\-display\-file ", " \-\-display\-track\-file " \fIfilePath\fR" Sets the file to output the current track's path to every time a track is played. This is mostly useful for interfacing tools like OBS with http-music, for example so that you can display the name/path of the track that is currently playing during a live stream. .TP .BR \-w ", " \-\-write\-playlist ", " \-\-write ", " \-\-save " \fIfilePath\fR" Writes the active playlist to a file. This file can later be used with \fB\-\-open\fR; you won't need to stick in all the filtering options again. .SH STATUS LINES By using the \fB--status-line\fR option, a custom playback status line can be set. The basic idea is that strings like \fB%timeLeft%\fR, called "replacement strings", will be replaced with appropriate values (like \fB03:14\fR). A list of every such replacement string follows: .TP .BR %name% ", " %trackName% The name of the current track, e.g. \fBTimelapse Kingdom\fR. .TP .BR %longIndex% A "long" string that automatically contains information about the index of the current track, e.g. \fB(35 / 1572)\fR or \fB(35 / 1572 [All]; 1 / 11 [Group])\fR. (It only shows up like the second example when you're playing in a sort mode (see \fB--sort\fR) that plays the tracks of groups in order, such as \fBorder\fR or \fBshuffle-groups\fR.) .TP .BR %index% The index of the track in the entire track queue, e.g. \fB35\fR. .TP .BR %trackCount% The number of tracks in the entire track queue, e.g. \fB1572\fR. .TP .BR %indexGroup% The index of the track in the current group, e.g. \fB1\fR. Only exists if the sort mode (see \fB--sort\fR) is set to some option where the tracks in a group play in order (such as \fBorder\fR or \fBshuffle-groups\fR). (It's just an empty string otherwise.) .TP .BR %trackCountGroup% The number of tracks in the current group, e.g. \fB11\fR. As with \fBindexGroup\fR, only present according to the sort mode; otherwise an empty string. .TP .BR %duration% The duration of the track, e.g. \fB08:24\fR. In the format of "MM:SS", or "H:MM:SS" if the track is over an hour long. (MM and SS are padded, e.g. 03 instead of 3, but the number of hours isn't padded.) .TP .BR %timeDone% The time currently passed in the track, e.g. \fB03:10\fR. Formatted the same way as \fB%duration%\fR. .TP .BR %timeLeft% The time that remains in the track, e.g. \fB05:14\fR. Formatted the same way as \fB%duration%\fR. .TP .BR %esc% The escape string; equal to \fBESC\fR, \fB\\x1b\fB, \fB\\003\fR. You can use this to do fancy formatting tricks, like showing the name of the track in blue: \fB%esc%[34m%name%\fR. .SH FILTERS Filters are simple pieces of JSON text used to indicate exactly what songs http-music should select to play from a playlist. A basic filter might look something like \fB{"tag": "name.length", "most": 10}\fR. Filters can be specified in two ways: .TP 1) By using the \fB--filter\fR (shorthand \fB-f\fR) option. For example: \fBhttp-music play --filter '{"tag": "name.length", "most": 10}\fR. .TP 2) By passing the filter directly into the playlist's JSON file, under the \fB"filters"\fR field. For example: \fB{"source": ["open-file", "playlist.json"], "filters": [{"tag": "name.length", "most": 10}]}\fR. .PP Either of these ways have the same effect: only tracks whose names are at most 10 characters long are played. .PP Generally, filters can only access data that is available right inside the playlist file. If you try to pass \fBmetadata.duration\fR as the tag when there is no such value in the playlist file, \fBthe filter will not work.\fR Thus, the power of filters are unlocked primarily when using the \fBhttp-music process-playlist\fR command initially. This utility command automatically adds specific metadata information, such as duration, to the \fBmetadata\fR property of each track. That metadata can then be accessed using filters, for example \fB{"tag": "metadata.duration", "least": 180}\fR. .PP Generally, every filter must have a \fB"tag"\fR property as well as at least one other property (and potentially more) used to check the value of that tag. The \fB"tag"\fR property is simply a path to any property on the track; for example, \fBmetadata.bitrate\fR means the \fBbitrate\fR property found on the track's \fBmetadata\fR, so 18000 in \fB{"name": "Cool track", "metadata": {"bitrate": 18000}}\fR. A list of every property follows: .TP .BR gt " \fIamount\fR" Checks if the tag value is greater than the given amount. \fB{"tag": "metadata.duration", "gt": 30}\fR only keeps tracks which are more than 30 seconds long. .TP .BR lt " \fIamount\fR" Checks if the tag value is less than the given amount. \fB{"tag": "metadata.duration", "lt": 120}\fR only keeps tracks which are less than 120 seconds long. .TP .BR gte ", " least ", " min " \fIamount\fR" Checks if the tag value is greater than or equal to the given amount. \fB{"tag": "metadata.duration", "gte": 300}\fR only keeps tracks that are at least five minutes long. .TP .BR lte ", " most ", " max " \fIamount\fR" Checks if the tag value is less than or equal to the given amount. \fB{"tag": "metadata.duration", "lte": 60}\fR only keeps tracks that are 60 seconds or shorter. .TP .BR includes ", " contains " \fIvalue\fR" Checks if the tag value contains the given value. \fB{"tag": "name", "contains": "the"}\fR only keeps tracks whose names contain "the" (case-sensitive). \fB{"tag": "genres", "contains": "jazz"}\fR only keeps tracks whose "genres" tag contains "jazz". (There is not officially a property "genres" on http-music tracks, but this could be added to a playlist file by hand.) .TP .BR regex " \fIre\fR" Checks if the tag value matches the given regular expression. \fB{"tag": "name", "regex": "^[Aa]"}\fR only keeps tracks whose names begin with "A" or "a". .SH EXAMPLES Basic usage: .PP .nf .RS $ http-music play .RE .fi .PP Generate a playlist from an HTTP server: .PP .nf .RS $ http-music crawl-http http://example.com/path > playlist.json .RE .fi .PP Generate a playlist from the local file system: .PP .nf .RS $ http-music crawl-local /example/path > playlist.json .RE .fi .PP Open a specific playlist file: .PP .nf .RS $ http-music play --open playlist2.json $ http-music play -o playlist2.json .RE .fi .PP Only play music under a specific group: .PP .nf .RS $ http-music play --clear --keep 'Cool Author 72' $ http-music play -c -k 'Cool Author 72' $ http-music play -c -k 'Cool Author 72/Good Album' .RE .fi .PP Don't play music under a specific group: .PP .nf .RS $ http-music play --remove 'Bad News' $ http-music play -r 'Bad News' $ http-music play -x 'Bad News' .RE .fi .PP Don't play music under a specific group, except for a sub-group: .PP .nf .RS $ http-music play --remove 'Bad News' --keep 'Bad News/Irony' $ http-music play -x 'Cool Author 72' -k 'Cool Author 72/Good Album' .RE .fi .PP Play every group in a random order, playing each group in its own original order: .PP .nf .RS $ http-music play --sort shuffle-groups .RE .fi .PP Play every group in a random order, after collapsing the playlist, so that parent groups aren't considered (using \fB--sort shuffle-groups\fR alone would play all of one artist's albums before moving onto the next; using \fB--collapse\fR lets the groups be shuffled without regarding the artists' groups): .PP .nf .RS $ http-music play --collapse --sort shuffle-groups .RE .fi