PM123 currently understands the following commands for controlling the playback engine. Optional parameters are enclosed in square brackets.
| Command | Description | Reply |
|---|---|---|
| load <url> [<url> [...]] (2.) | Loads one or more file
or URL
into the player. Any currently playing item will be aborted. Specifying more than one file is equivalent to dropping multiple items on the player. This implicitly modifies the default playlist. The file names may be enclosed in double quotes ("). |
Result code, non-zero = error. |
| play [<url> [<url> [...]]] (2.) | Starts playing. If at least one file or URL was specified, it will be first loaded and playback will be started. See load for details. Any currently playing item will be aborted. |
Result code, non-zero = error. |
| enqueue <url> [<url> [...]] (2.) | Plays a set of files
or URLs
after the current playback has completed. This command will always
append to the default playlist. If the default playlist is not yet in
use it is cleared and the currently loaded object is placed as first
element if any. This will never intercept any active playback. The file names may be enclosed in double quotes ("). |
Result code, non-zero = error. |
| invoke [<url> [<url> [...]]] (2.) | Same as play if "play on load" is set, same as load otherwise. | Result code, non-zero = error. |
| stop | Stops playback. | Result code, non-zero = error. |
| pause [on|off] (1.) | Pauses or resumes the playback. | Result code, non-zero = error. |
| rewind [on|off] (1.) | Toggles or (re)sets rewind of the currently playing file. If rewind is activated fast forward is implicitly deactivated. | Result code, non-zero = error. |
| forward [on|off] (1.) | Toggles or (re)sets fast forward of the currently playing file. If fast forward is activated rewind is implicitly deactivated. | Result code, non-zero = error. |
| next [<count>] (2.) | Selects the next song in playlist. If <count> is specified, you can skip more than one song at once. | Result code, non-zero = error. |
| prev [<count>]
(2.) previous [<count>] |
Selects the previous song in playlist. If <count> is specified, you can skip more than one song at once. | Result code, non-zero = error. |
| jump <n> | Jump to <n>
seconds in the currently playing file. <n>
may be a fractional number. Note that jump is not reliable in playlist mode, because the currently playing song may change just before jump is executed. You should prefer navigate in this case. This can restore the previous song in doubt. |
Result code, non-zero = error. |
| navigate [/;|..;|.;] [<item>;[<sub item>;[...]]] [<time>[%]] | Navigate within
the currently loaded playlist. Examples: 'navigate /;D:\songs\song1.mp3' navigates to the start of the song within the currently loaded playlist. If the file is referenced twice, the first instance is taken. navigate uses the location string syntax. 'navigate D:\songs\song1.mp3;1:02.7' navigates to location 62.7 seconds within the next occurrence of D:\songs\song1.mp3. |
Result code, non-zero = error. |
| savestream [<file>] | Save stream to the specified file (if the decoder supports that). savestream without a file argument stops saving a stream. | Result code, non-zero = error. |
| volume [[+|-]<n>] | Sets volume to <n>% (scale 0-100, of course). If a sign is included, <n> is added to the current volume level. If <n> is omitted the volume is unchanged. | Previous volume setting or empty on error. |
| shuffle [on|off] (1.) | Toggles or (re)sets shuffling. | Result code, non-zero = error. |
| repeat [on|off] (1.) | Toggles or (re)sets repeat. | Result code, non-zero = error. |
| query play | pause | rewind | forward | repeat | shuffle | Return whether the player is playing, paused, in rewind mode, in fast forward mode or whether repeat or shuffle is activated. | 0 = off, 1 = on, blank = error, invalid request |
| current [song|root] | Query the current song or the currently loaded
playlist. If only one song is currently loaded into the player current
root
will also return the song. By default current returns the current song. |
Current objects URL or empty if none. |
| status tag|file|info | Returns the information currently displayed in the
scroller or returns nothing if "no file loaded". You should not use this command to access meta informations about the current song. Use the info commands for this purpose. |
Info string. |
| time | Return the current playing time from the start of the current song. This is the time displayed in the PM123 main window. If no playback is active and a resume position has been saved it is returned. time is the opposite of jump. | Playing time in seconds, -1 if not available or empty on error. |
| location | Query the current playing location. In contrast to time location always return a navigation string starting at the current root and ignoring any slices. location is the opposite of navigate. | Location string or empty if none. |
All boolean parameters may use on, 1, true or yes for the logical value true, off, 0, false or no for false and toggle or no argument to flip the current setting.
If you pass relative URLs the path set with the cd command is used as root. Note that this does not apply to location string.
In PM123 before version 1.40 the playlist manipulation commands always operate on the currently playing item. Now the new commands pl prev, pl next and pl reset are dedicated to playlist operations.