iNetControl - XMMS control via an TCP/IP connection ** Overview: iNetControl allows you to control most aspects of the XMMS music player via a text based command language over a standard network socket. The protocol/command structure is very similar to the text command and response protocol used by FTP. The protocol is easy to parse and format for programs and humans alike. ** Connection: iNetControl allows up to 64 simulataneous client connections. Incoming connections can have source IP address security applied and/or user & password security applied or no security. By default, the iNetControl server is listening on port 1586, though you can change that in the configuration panel (Xmms->Preferences->Options->General Plugins). When a client first connects, it will receive a welcome message (message code 000). If user/password security is enabled, they will not receive any other updates until authenticated. Once authenticated (if user security is enabled), the user will receive several status messages. The exact number depends on what the player is doing at the time of the connection, but you can count on receving a 010 status message with the players current state. NOTE: At this time, IP address security and user/password security are not implemented. The USER command can be used, but is a NOP. As such, as soon as the client connects, they'll receive a welcome status message immediatly followed by various status messages. When designing a client to communicate with iNetControl, it's critical that you take an event driven approach to handling status/responses from iNetControl. Since the user can be directly interacting with the XMMS GUI (or another plugin can be) or other iNetControl clients may be, you cannot guarantee the frequency or order of responses and status messages. You should never miss receiving a state change message, but this state change may have happened just as you sent a command, resulting in a status message that may not match what you expect. If you keep the status message handler event driven and stateless, you should be fine. But if you ever put your client to sleep waiting for a specific response/status code, there are times you may never wake. Emperical testing may tell you that this is hogwash and it appears to work synchronously. You are free to ignore this advice, but be aware that sometime under some circumstance, those assumptions will likely fail. ** Message Format: All commands, responses and messages are sent as text. Each text line sent from iNetControl is terminated with a CR (ASCII 13) and an LF (ASCII 10). Commands sent to iNetControl should similarly be terminated with a CR and LF, though a single LF will work and is supported. ** Testing: You can test the plugin by installing and activating it (read INSTALL) and then using telnet to connect to the machine XMMS is running on at port 1586. For example, if you are running XMMS on the same machine you are going to run telnet, you'd type $ telnet localhost 1586 To send a command, simply type it in and press ENTER. Status messages will come across, one per line, as appropriate from the iNetControl server. ** Command Overview: Commands are in the form of a command name followed by any arguments. Commands can be in any case (i.e. they are not case sensitive), though they will be listed in upper case to help them standout. Parameters may be case senstive (specifically, file name specifications are case sensitive because unix/linux file names are case sensitive). Command response isn't guaranteed and certainly isn't synchronous. Most commands generate a response simply because they change the state of the player and that triggers a status message to be sent. It would not be a great idea to send a command and then wait for a specific response. While this might work, it's not how the interface is designed and you may find yourself facing occasionally unreliable responses (i.e. waits forever, etc). Remember that the player can be controlled not only via your connection, but also from the GUI and from other connections through iNetControl. Command and arguments are delimited with a space. If an argument has a space in it, you can either quote the argument (single or double quote) or use the \ (backslash) to quote that single character. ** Command Summary: SECURITY: USER name PASSWORD word Authenticate the your connection with a valid user name and password. If user level security is enabled, no other commands will work until you have successfully authenticated. NOTE: In this version, this command is allowed, but ignored. Connections are always allowed whether authenticated or not. PLAYER CONTROLS: LOAD_FILE path/filename ... Causes XMMS to stop playing (if it is playing), clear out its current playlist and load each file specified. You can have a maximum of 63 files on a single command. Files can be music files (i.e. mp3) or playlists (m3u) or both. This will not automatically start playing the files - use the PLAY command for that. PLAY_FILE path/filename ... Causes XMMS to stop playing (if it was), clear out its current playlist, load each file specified and then start playing those files. You can specify a maximum of 63 files in a single command. Files can be music files (i.e. mp3), playlists (m3u) or both. CLEAR_PLAYLIST Stops playing (if we are playing) and clears out the current playlist tracks. APPEND_FILE path/filename ... (**) Appends the file or files to the current playlist in the order they are listed to the current playlist REMOVE_TRACK trackNum Removes the track number from the current playlist. Any Tracks after the removed track "slide up" in position (important to keep in mind if deleting a number of tracks at once). A tip: if you need to delete multiple tracks, delete them in descending order (i.e. highest track # first) as that will eliminate having to recompute the track #s after each delete. PLAY Causes XMMS to being/resume playing. If the player had been paused, it will resume playing from where it was paused. If the player had been stopped, it will start playing from where it was last left off or from the start. If there is no files to play, it will immediatly return to a STOPPED state. PAUSE If the player is playing, PAUSE will put play on hold (you know, pause it :-). If the player is paused or stopped, the PAUSE command will do nothing. You can resume playing with the RESUME command. RESUME If the player is paused, RESUME will resume play where it was left off. If the player is already playing or is stopped, the RESUME command will do nothing. NEXT_TRACK Advance the player to the next track in the playlist, if any. If the player is in random/shuffle mode, this may not be the next track you expect. PREV_TRACK Move the player back to the previous track in the playlist, if any. JUMP_TO_TRACK track# Move the player to the specified track # index within the playlist. If the track # is out of range, the command is ignored and an error code 004 is returned. Track #s are 0 based (so it you have 5 tracks, valid track numbers are 0 to 4). JUMP_TO_TIME timeindex Move the player to "timeindex" seconds into the current track. Time is just the seconds into the track. So a time index of 0 is the start of the track (rewind). "timeindex" 120 is two minutes into the song. Times are always formatted in simple # of seconds, no "colon" notation of minutes and seconds - just seconds. Trying to set a time index outside the length of the current song will be ignored and return an error 004. HIDE_PLAYER When invoked, all visible portions of the xmms player are made invisible. This is used primarily for when XMMS is meant to hide in the background and be interacted with. STOP Stops the player if it was paused or playing. VOLUME n Sets the players main volume control to a value from 0 to 100%. Only include the number, no % (percent) sign i.e. VOLUME 50 SHUFFLE on/off Enables or disables shuffle (random) mode. If the command is given with no parameter, shuffle mode is turned on. Otherwise, the parameter needs to be the word ON or OFF (case does not matter). REPEAT on/off Enables or disables repeat mode. If the command is given with no parameter, repeat mode is turned on. Otherwise, the parameter needs to be the word ON or OFF (case does not matter). QUIT This will stop the player and shutdown XMMS and, consequently, the clients connection (well, all client connections). SESSION CONTROLS: These controls affect only the client connection. They will not affect the player itself or other client connections - you may consider them "local" in scope. TIME_UPDATES on/off TIME_UPDATES controls whether your client receives periodic updates on the progress of the currently playing track. These are typically sent once per second, though processing delays may cause them to occasionaly be delayed. By default, a new connection will receive status updates. If you have no need for them, you can disable them and potentially save a little bit of bendwidth. Status updates are under response code 013. If TIME_UPDATES is sent with no parameters, updates are enabled. Otherwise, the parameter must be the word ON or OFF. PLAYLIST_UPDATES on/off PLAYLIST_UPDATES controls whether changes to the playlist (either ones that the client requests or someone else) trigger a dump of the contents of the playlist (tracks, lengths, files, etc). By default, this is disabled as it can generate a lot of traffic (I have playlists with literally thousands of tracks!). These updates are sent under response code 014. If PLAYLIST_UPDATES is sent with no parameters, updates are enabled. Otherwise, the parameter must be the word ON or OFF. FORMATTED_TIME on/off Whenever times are reported to the client, by default they are formatted as standard H:MM:SS times (i.e. 1:30:20 for 1 hour, 30 minutes and 20 seconds). In some situations, you may want the times in raw seconds so that you can format them yourself (i.e. 137 instead of 0:02:17). FORMATTED_TIME allows you to control whether the response are formatted as H:M:S or seconds. By default, a new client will receive formatted times. If the FORMATTED_TIME command is sent with no parameters, formatted times are enabled. Otherwise, the parameter must be ON or OFF. REQUEST STATUS This will result in iNetControl eventually sending a code 010 which indicates the players status. Note that while response is usually almost instantaneous, there are a number of reasons why the response may be delayed. REQUEST PLAYLIST This will result in iNetControl eventually sending a code 012 with current playlist info. REQUEST PLAYLIST_TRACKS This will result in iNetControl eventually sending a code 014 (actually, a lot of code 014s) with current playlists tracks and info. REQUEST TRACK This will result in iNetControl eventually sending a code 011 with current track info. REQUEST POSITION This will result in iNetControl eventually sending a code 013 with the position/time into the currently playing track. REQUEST ALL This will result in iNetControl eventually sending as many status message codes as make sense. You can always expect a code 010 back. Depending on the state of the player, you may also receive a combination of the other status codes (010-019). EXIT Closes the current client connection logically. Note that while this is nice to issue, it's also perfectly OK to just close the network connection. iNetControl will pick this up and gracefully shutdown your connection. ** Status/Response Overview: Status/Reponse codes are sent from iNetControl to your client as events and transitions in the player dictate or in response to a REQUEST command. All status/responses start with a 3 digit code, followed by a number of parameters. Each parameter is delimited by a space. If a parameter is to contain a space, the parameter will be quoted (double or single, as the case may dictate). Further, it is possible special characters (like space) may be quoted with a \ (backslash - single character quote). ** Response Code Summary: COMMAND/PROTOCOL RESPONSES: 000 - Welcome/connection message This response is the first thing that a new client will receive. It includes the response code, the name of the XMMS server host, the identifier that this is in fact the iNetControl server and the version of the iNetControl server. Here is a sample of this response 000 homer.cdp1802.org IXMMS_NETCTL server (Version V0.2.0) ready. 001 - Authentication needed/failure indicator Sent when an attempt to authenticate the user name/password fails, when IP security prevents the connection or when a user attempts to execute a command before user authentication (if enabled) has completed. The parameters are usually just "NOT AUTHENTICATED", but may be a text message to help explain the failure in more detail. Here is a sample response 001 NOT AUTHENTICATED 002 - Unrecognized command or parameters Sent in response to a command that is nore recognized. The parameters are usually "UNKNOWN COMMAND", but may by a test message to explain the failure in more detail. 003 - Too few/many arguments Sent in response to a command that has too few or too many arguments for the command. It implies the command itself is recognized, but because of incorrect parameters, cannot be executed. The parameters to this message are usually "TOO FEW ARGUMENTS" or "TOO MANY ARGUMENTS", but this may be other text to further clarify the failure. 004 - Unrecognized Argument/invalid argument Sent in response to a command that has an unrecognized parameter. It implies the command itself is recognized, but the parameter doesn't fall into the range of acceptable values. THe parameters to this response message are usually "INVALID ARGUMENT", but this may be other text to further clarify the failure. 005 - Last request processed OK Sent in response to any command from above. The first parameters are the command itself (and it's parameters). PLAYER/STATUS CODES: NOTE: The format of the parameters described below will never change, nor will their order. However, additional parameters may be added as iNetControl matures and XMMS is extended to provide more data to it's clients. You should code your client to allow for additional arguments not described below to be silently ignored (until you decide to update your client to support them). 010 - Current player status Sent upon successfull client connection and from then on whenever the players status changes (for any reason). The format of the command is the identifer, then the word PLAYING, PAUSED or STOPPED to indicate what the player is doing. That is followed by a number 0-100 representing the players current main volume (0-100%). The is followed by a indicator of shuffle mode. It will either be SHUFFLE if shuffle mode is on or NORMAL if not. This is followed by an indicator of repeat mode. It will either be REPEAT for repeat mode or SINGLE for single play (non-repeat mode). Here is a sample 010 PLAYING 100 SHUFFLE REPEAT 011 - Current track info Sent whenever the player transitions from stop to playing or when the player ends one track and moves on to another. If the player is playing when you initially connect to iNetControl, you'll receive this status as well. The format of the command is track title, track file name, track length, encoded bit rate (if applicaple), sampling rate the data was recorded at and number of channels of audio in the track. Currently, XMMS does not provide specific album/artists/track/track #/genre/etc information to it's clients. The title is what you see on the XMMS face when it is playing a track. The file name is provided to allow you to use a MP3 tool/library to extract more specific information, should you need it. Here is a 011 "A-Ha - Take on me" "/usr/opt/mp3/aha/takeme.mp3" 0:1:57 128 44 2 012 - Current Playlist info Sent whenver the player is playing a playlist and transitions from one track of the list to another. If the player is playing when your client connects, you will receive this status message as well. The message includes the position in the playlist the current track is and the total number of tracks in the playlist. Here is an example: 012 5 104 013 - Track playing status update Sent whenever the player is playing a track. It includes the position in the current track as well as the total time of the track. This is useful for updating any status/progress indicators you may be keeping. The first parameter the current position/time in the track and the second is the total track time. Generally, you can expect these messages about once per second, though there are no promises. By default, new connections will receive these whenever the player is playing a track. if you do not want or need them, you can disable them with the TIME_STATUS OFF command. You would still be able to request them "on demand" via REQUEST POSITION. Here is an example: 013 0:01:20 0:04:31 014 - Playlist content update Sent whenever the client issues a REQUEST PLAYLIST_TRACKS or when the play list changes and PLAYLIST_UPDATES it set. You'll always receive a minimum of 2 014 messages - the header and trailer. You'll also receive one message for each track in the playlist. The format looks like this (for a two track playlist) 014 START 2 "my playlist" "my playlist.m3u" 014 0 "A-Ha - Take on me" "/usr/opt/mp3/aha/takeme.mp3" 0:1:57 014 1 "Drive - The Cars" "/usr/opt/mp3/cars/drive.mp3" 0:4:13 014 END 2 The first parameter is either START (indicating the start of a playlist update), the actual play list track # or END indicating the end of the play list records. Once you receive an 014 START, you will only receive 014 messages until the 014 END is received - other messages will not be mixed in. However, building your code so it doesn't depend on this will make things more robust. 014 START includes the number of tracks you are about to receive as well as the name of the playlist and the file spec for the playlist. As of right now, iNetControl cannot always determine the playlist name and file. In fact, it can only if the client that is requesting this is also the one that request the playlist be LOADed or PLAYed. When we can get that info directly from xmms, this will be available regardless of who loaded the playlist. 014 <file> <length> You receive one of these per track in the playlist. The track # is the index into the playlist and corrosponds to the track # you receive from an 012 message or a JUMP_TO_TRACK command. Title and file name are what you'd expect. Time is the length of this track. It will be formatted based on the current setting for this client (formatted or just seconds). 014 END indicates the end up this playlists tracks. It also includes the number of tracks you should have just received.