1Control interface to generic frontends 2 3The generic remote interface allows frontends to easily control 4mpg123 by commands through stdin/stdout. To start the generic 5remote interface, start mpg123 with parameter -R. 6 7In case of a frontend that starts mpg123 with the -s option to read the audio from stdout, the --remote-err option is automatically activated to send responses to stderr so that stdout stays clean for audio. 8 9(Still the case?) 10As an example it's used by IRMP3, a tool that allows you to 11control mpg123 with a standard infrared remote control. See 12http://www.fasta.fh-dortmund.de/users/andy/irmp3/ for more 13information. 14 15You can also specify --fifo <path> to create a named pipe at <path> and listen on that for commands instead stdin. 16That way, you can deliberately control mpg123 by echoing into the named pipe from any terminal / program. 17The command respones are still sent to standard out or standard error (depending on -s or --remote-err switches). 18 19 20COMMAND CODES 21------------- 22 23You can get this info via the control command "help". 24 25 26HELP/H: command listing (LONG/SHORT forms), command case insensitve 27 28LOAD/L <trackname>: load and start playing resource <trackname> 29 30LOADPAUSED/LP <trackname>: load but do not start playing resource <trackname> 31 32LOADLIST/LL <entry> <url>: load a playlist from given <url>, and display its entries, optionally load and play one of these specificed by the integer <entry> (<0: just list, 0: play last track, >0:play track with that position in list) 33 34PAUSE/P: pause playback 35 36STOP/S: stop playback (closes file) 37 38JUMP/J <frame>|<+offset>|<-offset>|<[+|-]seconds>s: jump to mpeg frame <frame> or change position by offset, same in seconds if number followed by "s" 39 40VOLUME/V <percent>: set volume in % (0..100...); float value 41 42MUTE: turn on software mute in output 43 44UNMUTE: turn off software mute in output 45 46RVA off|(mix|radio)|(album|audiophile): set rva mode 47 48EQ/E <channel> <band> <value>: set equalizer value for frequency band 0 to 31 on channel 1 (left) or 2 (right) or 3 (both) 49 50EQFILE <filename>: load EQ settings from a file 51 52SHOWEQ: show all equalizer settings (as <channel> <band> <value> lines in a SHOWEQ block (like TAG)) 53 54SEEK/K <sample>|<+offset>|<-offset>: jump to output sample position <samples> or change position by offset 55 56SCAN: scan through the file, building seek index 57 58SAMPLE: print out the sample position and total number of samples 59 60FORMAT: print out sampling rate in Hz and channel count 61 62SEQ <bass> <mid> <treble>: simple eq setting... 63 64PITCH <[+|-]value>: adjust playback speed (+0.01 is 1 % faster) 65 66SILENCE: be silent during playback (meaning silence in text form) 67 68STATE: Print auxiliary state info in several lines (just try it to see what info is there). 69 70TAG/T: Print all available (ID3) tag info, for ID3v2 that gives output of all collected text fields, using the ID3v2.3/4 4-character names. NOTE: ID3v2 data will be deleted on non-forward seeks. 71 72 The output is multiple lines, begin marked by "@T {", end by "@T }". 73 74 ID3v1 data is like in the @I info lines (see below), just with "@T" in front. 75 76 An ID3v2 data field is introduced via ([ ... ] means optional): 77 78 @T ID3v2.<NAME>[ [lang(<LANG>)] desc(<description>)]: 79 80 The lines of data follow with "=" prefixed: 81 82 @T =<one line of content in UTF-8 encoding> 83 84meaning of the @S stream info: 85 86S <mpeg-version> <layer> <sampling freq> <mode(stereo/mono/...)> <mode_ext> <framesize> <stereo> <copyright> <error_protected> <emphasis> <bitrate> <extension> <vbr(0/1=yes/no)> 87 88The @I lines after loading a track give some ID3 info, the format: 89 90 @I ID3:artist album year comment genretext 91 where artist,album and comment are exactly 30 characters each, year is 4 characters, genre text unspecified. 92 You will encounter "@I ID3.genre:<number>" and "@I ID3.track:<number>". 93 Then, there is an excerpt of ID3v2 info in the structure 94 @I ID3v2.title:Blabla bla Bla 95 for every line of the "title" data field. Likewise for other fields (author, album, etc). 96 97 98RESPONSE CODES 99-------------- 100 101Note: mpg123 returns errors on stderr, so your frontend should 102 look not only at stdout but also at stderr for responses. 103 It is a good idea to use --remote-err and just look at stderr. 104 105@R MPG123 (ThOr) v7 106 Startup version message. Everything after MPG123 is auxilliary information about behaviour and command support, ID3v2 tag support is new in v3. 107 108@I ID3:<a><b><c> 109 Status message after loading a song (ID3 song info) 110 a = title (exactly 30 chars) 111 b = artist (exactly 30 chars) 112 c = album (exactly 30 chars) 113 d = year (exactly 4 chars) 114 e = comment (exactly 30 chars) 115 f = genre (string) 116 117@I ID3.genre:<number> 118@I ID3.track:<number> 119 Optional lines with additional ID3v1 info (if present): Genre ID and track number in set. 120 121@I ID3v2.title:<text> 122 After loading a track with ID3v2 info, such lines occur for every line of the "title" data field and likewise for other fields (author, album, etc). 123 124Since version 9, ID3 info is wrapped in 125 126@I { 127... 128@I } 129 130to guide parsers. 131 132@I <a> 133 Status message after loading a song (no ID3 song info) 134 a = filename without path and extension 135 136@I LISTENTRY <n>: <url> 137 printout of playlists loaded with LOADLIST 138 139Since version 9, list printout is wrapped in 140 141@I { 142... 143@I } 144 145to help parsers decide if they got the whole list. 146 147@S <a> <b> ... 148 Stream info at beginning of playback, meaning 149 S <mpeg-version> <layer> <sampling freq> <mode(stereo/mono/...)> <mode_ext> <framesize> <stereo> <copyright> <error_protected> <emphasis> <bitrate> <extension> <vbr(0/1=yes/no)> 150 151@S <a> <b> <c> <d> <e> <f> <g> <h> <i> <j> <k> <l> 152 Status message after loading a song (stream info) 153 a = mpeg type (string) 154 b = layer (int) 155 c = sampling frequency (int) 156 d = mode (string) 157 e = mode extension (int) 158 f = framesize (int) 159 g = stereo (int) 160 h = copyright (int) 161 i = error protection (int) 162 j = emphasis (int) 163 k = bitrate (int) 164 l = extension (int) 165 166@F <a> <b> <c> <d> 167 Status message during playing (frame info) 168 a = framecount (int) 169 b = frames left this song (int) 170 c = seconds (float) 171 d = seconds left (float) 172 173@P <a> 174 Playing status 175 a = 0: playing stopped 176 a = 1: playing paused 177 a = 2: playing unpaused 178 179@E <a> 180 An error occured 181 Errors may be also reported by mpg123 through 182 stderr (without @E) 183 a = error message (string) 184 185@J <n> 186 Jumped to frame n. 187 188@RVA <mode> 189 Switched to specified RVA mode. 190 191@V <volume>% 192 Set volume to specified value (float, percent). 193 194@<x> : <y> : <z> 195 Set equalizer value z for band y of channel x. 196 197@bass: <b> mid: <m> treble: <t> 198 Set simple equalizer control for bass, mid, treble. 199 200@T <response from TAG command> 201 The output is multiple lines, begin marked by "@T {", end by "@T }". 202 ID3v1 data is like in the @I info lines, just with "@T" in front. 203 An ID3v2 data field is introduced via ([ ... ] means optional): 204 @T ID3v2.<NAME>[ [lang(<LANG>)] desc(<description>)]: 205 The lines of data follow with "=" prefixed: 206 @T =<one line of content in UTF-8 encoding> 207 208 209EQUALIZER CONTROL (History) 210--------------------------- 211 212WARNING: The interpretation of the command arguments changed. The channel is either 1 or 2 or 3 (left, right, both). 213It used to be 0 or 1 for left or right but the change slipped through during libmpg123 work and now it is a fact. 214Sorry. 215 216Cold Feet Audio Patch for MPG123 217 21810.07.2002 219 220This is a dirty little hack to enable the equalizer in mpg123's 221generic_control interface. It works like this, there are two 222different channels on the equalizer and 32 frequencys. 223 224The hack just enables mpg123's built in equalizer to run real-time. 225We haven't built in any capability to save the eq, you're frontend 226will have to handle that part, and init the eq on the startup of 227mpg123. 228 229K, it works like this: 230 231#./mpg123 -R - <---- This command will start mpg123 in 'frontend' mode. 232 233If you want to send it some eq values you'd send it: 234eq X Y V[ENTER] 235 236X = The channel. It can be either 0 or 1. I haven't put any error checking 237 in, so it probably wouldn't be a good idea to go out of bounds. (integer) 238Y = This is the frequency, it can be 0 to 31. 0 being closer to treble and 239 31 being closer to bass. (integer) 240V = The raw value of your equalizer setting. I've found that the values work 241 best between 0.00 and 3.00. When mpg123 starts up, all of them are set 242 to 1.00. 243 244OK, have fun! If you have any questions or found some bugs, please contact 245nutcase@dtmf.org 246 247Thanks, 248nut 249 250Note by Thomas Orgis: The contact appears to be dead. 251