MARS Scripting Interface ======================== Mars scripts are controlled in a similar way to CGI scripts on a web server. Mars populates a number of environment variables, e.g. the names of the Artist and runs the script. Scripts may be entered directly into the plugin command column in the configuration. e.g. "$BROWSER" "http://www.google.com/search?q=$ARTIST", or the script to run may be named. If script idetifies itself with as "attached" it may interact with Mars via a HTTP like interface. Any language may be used but Python is preferred due to the good syntax and massive number of libraries installed "out of the box". Script tags =========== Mars scripts may have details embedded in them. The lines are in the form KEY = VALUE with an optional # at the beginning of the line. Single (') or double ("") quotes and semi-colons (;) around the VALUE are ignored. Values are assumed to be UTF-8. The following lines are valid: # title = My Script title = "My Script"; title=My Script # title = My Script the default title to be displayed in the popup menus and error messages # attached = true the plugin will send commands to Mars via the Mars Scripting Interface # install on = true the plugin will be turned on by default # help = # help = # help =

A Web Site Plugin

# help = Sign up at A web site. # help = # help = Help text in simple HTML. Use

for the main title. Use

for sub titles. # type = TYPE[/FIELD[,FIELD...]] # type = Artist # type = AlbumInfo/type,year identifies that type of the plugins TYPE is one of Background, Library, Artist, Album, Track or AlbumInfo AlbumInfo may be suffixed with the fields it provides, e.g. AlbumInfo/cover AlbumInfo/cover,year,type # end of headers # end of headers ======================================= the end of the headers lines below this will not be read for script tags The following values are just for documentation: # author = Gene Thomas # version = 1.0 # email = gene@genethomas.com # web = http://genethomas.com # mars-version = 2.1 The minimum mars version required to run the plugin Configuration parameters can be also be specified. Plugins are configured through the Configuration screen and the value accessed from the script through GET /config/TITLE/KEY # config/KEY = TYPE [; PARAMS] KEY may be user/$USER/KEY to specifiy a parameter that may be separately for each Mars user TYPE can be: string parameters: default sets the default value comment set the tooltip password string but value is not readablt on screen, e.g. show as "*****" parameters: default sets the default value comment set the tooltip int a whole number parameters: default sets the default value comment set the tooltip bool "true" or "false" parameters: default sets the default value comment set the tooltip directory select a directory parameters: default sets the default value comment set the tooltip examples: # config/host = string; default="myhost.com"; comment="the host to listen on" GET /config/host e.g. GET /config/host # config/port = int; default=1234 GET /config/port e.g. GET /config/port # config/user/$USER/login = string GET /config/user/USER/password e.g. GET /config/user/Fred/login # config/user/$USER/password = password GET /config/user/USER/password e.g. GET /config/user/Fred/password Environment variables and current directory =========================================== All UTF-8 text Note that the Artist, Album and Track names may not match the directory names, e.g when the Path Template was "Artist\Album\Num Track" as Unicode full width character, which allow Windows to have filenames such as AC/DC and Dr Who?, are converted back to the standard ASCII as this more correct. $MARS_HOME Directory where mars executes from. $MARS_PID The process ID of Mars. $BROWSER Path to the configured web browser. $PATH Prefixed with: the specific plugins directory (e.g. $MARS_HOME/Plugins/Album) the main Mars directory (i.e. $MARS_HOME) the Plugins driectory withing this (i.e. $MARS_HOME/Plugins) $PYTHONPATH Prefixed with: the plugins directory (i.e. $MARS_HOME/Plugins) $GT_TRACE "all", "-all" or comma separated list of trace flags, e.g. "-cgi,mars_si" mars.si Python module automatically reads this so mars.si.trace("text", num) writes to $MARS_HOME/Plugins/mars_si.log $MISC_ALBUM_NAME "misc" the name of the psuedo album that hold tracks in an artist that have no album $MARS_VERSION The Mars version in a human readable version string. In the form .[.][.| ] e.g. "2.0", "2.1.4", "3.4.5.6", "2.0 alpha 2", "2.3.5 beta 9" $MARS_VERSION_NUM The Mars version in a comparable format. This is in the form ----. A string the can be ASCIIbetically compared, e.g. > and < evaluate correctly is a = alpha b = beta r = release All numbers are padded to four digits with leading zeros. e.g: "2.1 alpha 3" is "0002-0001-0000-a-0003" "2.3.4" is "0002-0003-0004-r-0000" Python script development ------------------------- $MARS_SI_RESPONSE For testing scripts outside Mars. A path separator (; on Windows, : on Unix) separteds list of responses to send. "" for 200 OK A number, e.g. "404" for an error response A filename, e.g. "MyTrack.ini" to read the response from the filename e.g. "file.txt|404" Returns 200 OK when runs out of responses Background ---------- Current directory is the base directory of the collection with the greatest number of tracks. Library ------- Current directory is the base directory of the collection with the greatest number of tracks. Artist ------ $ARTIST The name of the Artist or "" if Artist is Various Artists $RATING The selected rating of the Artist "", "", "", "", "", or "" if not rated $DIRECTORY The Artist's absolute directory if descernable, "" otherwise If possible the current directory set to directory that most tracks identifiy as the Artist. Depends on Path Templates used to parse the Tracks' paths. Album ----- $ARTIST The name of the Artist or "" if Artist is Various Artists $ALBUM The title of the Album or "" if Album is misc $YEAR 4 digit year if album has a year, "" if not $HAS_COVER "true" if album has has cover, "" otherwise $TYPE The Type of recording, one of "album" "EP" Extended Play "single" Single "live" Live "best of" Best of "remix" Remix $RATING The selected rating of the Album "", "", "", "", "", or "" if not rated $DIRECTORY The Album's absolute directory if descernable, "" otherwise The "misc" album will have the Artist's absolute directory. If possible the current directory is set to directory that mose of the Track see as that of the Album. For the misc Album this is the directory of the Artist This Depends on Path Templates used to parse the Tracks' paths. Track ----- $ARTIST The name of the Artist or "" if Artist is Various Artists $ALBUM The title of the Albumor "" if Album is misc $TRACK name of the track, does not include track number or filename extension $FILENAME the absolute path to the file $RATING The selected rating of the Track "", "", "", "**", "*", or "" if not rated $NUMBER The track number if the Track has one, e.g, "3", or "" if not. $DAMAGED "true" if the Tracks is marked as damaged, "" otherwise $DIRECTORY The absolute directory of the track Current directory is the directory of the Track file (directory of $FILENAME). Interacting with Mars ===================== "Attached" scripts output HTTP requests. Mars responds with HTTP responeses: These: + always have a Content-Length + never Tranfer-Encoding: chunked + never compressed etc.. Example: Retreiving the number of a track GET /track/Pink Floyd/Dark Side of the Moon/On The Run/number Content-Length: 0 Response: MARS/1.0 200 OK Content-Type: text/plain; charset=UTF-8 Content-Length: 1 2 Example: Pressing the play button PUT /play MARS/1.0 Content-Length: 4 true Response: MARS/1.0 200 OK Content-Type: text/plain; charset=UTF-8 Content-Length: 0 Scipts may use standard Internet/Windows (CR LF) or Unix (LF) or line endings for headers. On Windows when transferring binary data such as images you must place stdout into binary mode: Python: impot os import msvcrt if os.name == "nt": msvcrt.setmode (0, os.O_BINARY) # stdin = 0 msvcrt.setmode (1, os.O_BINARY) # stdout = 1 All text is in UTF-8. Line endings are written as CR LF from Mars, as per Internet HTTP and Email (RFC 822) headers: -------- Content-Length: 24 mandatory the length of the data in bytes as per HTTP Content-Type: text/x-ini as per HTTP defaults to: text/plain; charset=UTF-8 See below for definition of the 'text/x-ini' Content-Type Information Methods =================== PUT /status content is text of general plugin status PUT /status/OPERATION content is text of status of a particular operation previous status' for the given action will be overwritten PUT /gauge content is a progess fraction overall or of a particular operation in the form "position/max", e.g. "9/1975" 'position' and 'max' must be integers PUT /gauge/OPERATION content is a progess fraction overall or of a particular operation in the form "position/max", e.g. "9/1975" 'position' and 'max' must be integers PUT /error Code: is a integer code (optional, defaults to 200 "Unknown error") Description: one line UTF-8 description of the error (optional, defaults to ) content (optional) is text details of the error Task Plugins ------------ PUT /tooltip set the tooltip of the task window "" to clear the tooltip PUT /gauge/tooltip set the tooltip of the gauge "" to clear the tooltip PUT /button/cancel/label set the label of the cancel button General Methods =============== GET|PUT /play Content-Type: text/plain; charset=UTF-8 (default) "true" or "false" false if stopped or paused GET|PUT /stop Content-Type: text/plain; charset=UTF-8 (default) "true" or "false" false if playing or paused GET /pause Content-Type: text/plain; charset=UTF-8 (default) "true" or "false" false if playing or stopped PUT /pause Content-Type: text/plain; charset=UTF-8 (default) "true", "false", "toggle" "toggle" to toggle on or off PUT /forward Skip track PUT /back Skip back track PUT /play-forward If playing skip track If sopped play PUT /stop-back If playing stop If stopped skip back track and play GET|PUT /volume floating point volume from "0.0" to "1.0" Can PUT "-" or "+" to adjust by an increment (1/20th) Can PUT a -n or +n to adjust, e.g. "+0.4" Can PUT a percentage, e.g. "34%" - or + of a percentage is relative to the current volume e.g: "+50%" when volume is "0.6" will set the volume to "0.9" To GET or PUT track position see GET|PUT /trackplaying/pos GET|PUT /mute "true" or "false" GET|PUT /repeat "true" or "false" GET|PUT /shuffle "none", "tracks", "albums" or "artists" GET /artist-names [?remote=false] A CR LF separated list of artist names (no CR LF at end) remote=true to include artists with only remote tracks, defaults to ignoring these. Note for Python user: This string is UTF-8 and since it is not processed by mars.IniFile which translates UTF-8 to Unicode, you should translate the result into Unicode yourself, e.g: mars.si.get(["artist-names"])[3].decode("utf-8") GET /artists [?remote=false] Content-Type: text/x-ini; charset=UTF-8 Dump of all artists. remote=true to include artists with only remote tracks, defaults to ignoring these. num-artists=2 [artist.0] name=Pink Floyd rating= [artist.1] name=Soundtracks grouping=true ; true if artist is a grouping of albums rather than an actual artist ; not written is false GET /user-names A CR LF separated list of user's names (no CR LF at end) GET /users Content-Type: text/x-ini; charset=UTF-8 Dump of all users. num-users=2 [user.0] name=general [user.1] name=A Friend remote=true GET /web-browser/URL Starts the configured web browser on the given URL GET /directory-browse/DIR Starts the configured directory browser, e.g. Windows Explorer, on the given directory DIR GET /directory-browse/PATH/DIR Starts the configured directory browser, e.g. Windows Explorer, on the given directory DIR Highlights the given FILE GET /start-terminal/DIR Starts the terminal (Command Prompt) in the given directory. GET /dialog/message [?title=] [&message=] [&icon=infomation] [&buttons=ok] interrupt the user with a pop up dialog box title is the title of the message box defaults to the title of the plugin message is the message to show defaults to nothing icon is one of "error", "information", "question" or "exclaimation" defaults to "information" button is a comma separated list of buttons to from "ok", "cancel", "yes", "no" "yes" or "no" imply the other. defaults to "ok" returns the button the user pressed, e.g. "ok" GET /dialog/int [?prompt=] [&title=] [&message=] [&value=0] [&min=0] [&max=100] interrupt the user to input an integer prompt if the main prompt title is the title of the message box defaults to the title of the plugin message is an optional message to show defaults to nothing value is the default value default to 0 returns "" if the user cancels the dialog otherwise returns the integer entered GET /dialog/string [?prompt=] [&title=] [&value=] interrupt the user to input an integer prompt if the main prompt title is the title of the message box defaults to the title of the plugin value is the default value defaults to "" returns "" if the user cancels the dialog otherwise returns the string entered Artist Methods ============== GET /artist/ARTIST [?remote=false] Content-Type: text/x-ini; charset=UTF-8 Dump of artist's information in .ini formt, UTF-8, CRLF line separated remote=true to include albums with only remote tracks, defaults to ignoring these. name=Pink Floyd rating=**** ; optional, not written if no rating ; "", "", "", "" or "" local=true ; true if has any local tracks ; optional, not written is true remote=false ; true if has any remote tracks ; optional, not written is false num-albums=2 [album.0] name=Dark Side of the Moon ; one section for each album, numbered from 0 ; all information as per GET /album/ARTIST/ALBUM ; except not track information ; etc... GET|PUT /artist/ARTIST/name The name of artist GET|PUT /artist/ARTIST/rating "" if no rating, otherwise "", "", "*", "**" or "*" GET /album/ARTIST/ "true" or "false" True if the artist has any local tracks. GET /album/ARTIST/remote "true" or "false" True if the artist has any remote tracks. GET /album/ARTIST/grouping "true" or "false" True if the artist is actually a category of albums rather than an actual artist, e.g. "Various Artists" GET|PUT /artist/ARTIST/play PUT "" or "true" to clear playlist and play the given album PUT "false" to stop playing if is playing GETs "true" if is playing else "false" GET|PUT /artist/ARTIST/enqueue PUT "" or "true" to enqueue the given album PUT "false" to unenqueue GETs "true" if is enqueued else "false" ?play=true Will start playing the enqueue track if not playing. Album Methods ============= GET /album/ARTIST/ALBUM [?remote=false] Content-Type: text/x-ini; charset=UTF-8 Dump of album's information in .ini formt, UTF-8, CRLF line separated remote=true to include remote tracks, defaults to ignoring these. artist=Pink Floyd name=Dark Side of the Moon ; $MISC_ALBUM_NAME for misc albums (holder for tracks with no album) type=TYPE ; "album", "EP", "single", "live", "best of", "remix", "bootleg" rating=** ; optional, not written if no rating ; "", "", "", "" or "" year=1975 ; optional, not written if year unknown has-cover=true ; "true" or "false" num-tracks=2 ; the number of tracks in the album local=true ; true if has any local tracks ; optional, not written is true remote=false ; true if has any remote tracks ; optional, not written is false [track.0] name=On The Run ; one section for each album, numbered from 1 as per a CD ; all information as per GET /track/ARTIST/ALBUM/TRACK ; etc... GET /album/ARTIST/ALBUM/name The name of the album $MISC_ALBUM_NAME for misc albums (holder for tracks with no album) GET /album/ARTIST/ALBUM/artist The name of the artist GET|PUT /album/ARTIST/ALBUM/type "album", "EP", "single", "live", "best of", "remix", "bootleg" GET|PUT /album/ARTIST/ALBUM/rating "" if no rating, otherwise "", "", "*", "**" or "*" GET|PUT /album/ARTIST/ALBUM/year "" if no year GET /album/ARTIST/ALBUM/has-cover "true" or "false" GET /album/ARTIST/ALBUM/local "true" or "false" True if the album has any local tracks. GET /album/ARTIST/ALBUM/remote "true" or "false" True if the album has any remote tracks. GET|PUT /album/ARTIST/ALBUM/cover GET fails with 404 if album does not have cover PUT "" to clear GET|PUT /album/ARTIST/ALBUM/play PUT "" or "true" to clear playlist and play the given album PUT "false" to stop playing if is playing GETs "true" if is playing else "false" GET|PUT /album/ARTIST/ALBUM/enqueue PUT "" or "true" to enqueue the given album PUT "false" to unenqueue GETs "true" if is enqueued else "false" ?play=true Will start playing the enqueue track if not playing. AlbumInfo plugins may omit the /album/ARTIST/ALBUM and submit the following: PUT /type PUT /rating PUT /year PUT /cover On Screen Playlist Methods ========================== GET /list Content-Type: text/x-ini; charset=UTF-8 num-tracks showing the length of the list One section, numbered from track.0, for each track in the list. that is a dump of track's information. As per /track/ARTIST/ALBUM/TRACK e.g: num-tracks = 2 pos = 0 [track.0] artist=Pink Floyd album=Dark Side of the Moon track=Speak to Me / Breath in the Air number=1 path=C:\Albums\Pink Floyd\Dark Side of the Moon\01 Speak to Me - Breath in the Air.mp3 [track.1] artist=Pink Floyd album=Dark Side of the Moon track=On The Run number=2 path=C:\Albums\Pink Floyd\Dark Side of the Moon\02 On The Run.mp3 GET|PUT /list-paths Content-Type: 'text/plain; charset=UTF-8' or compatible A CR LF sepatated list of paths of tracks. If any file can not be played all will be ignored. Write "" to clear the playlist. PUT /list-paths?keep=all Write a CR LF sepatated list of paths of tracks to add. PUT /list-paths?keep=playing Clear the playlist except the currently playing track. Write a CR LF sepatated list of paths of tracks to add. Write "" to clear the playlist except for the track that is playing. GET /list/length The length of the on screen playlist. e.g. "24" GET /list/pos The position in the playlist of the track being played e.g. "2" "" if not playing. Track methods ============= There are several ways to specify a track: /track/ARTIST/ALBUM/TRACK [?number=2] [?ext=.mp3] TRACK is the name of the track ALBUM may me empty to specify tracks with no album (shown as 'misc' in Mars) An optional number or filename extension may be added to refine the search. The number may be missing, e.g. 'number=' to speficy a track with no number. e.g. /track/Favorites/misc/Song?number= /tracknum/ARTIST/ALBUM/TRACKNUMBER [?ext=.mp3] TRACKNUMBER numbered from 1 ALBUM may me empty to specify tracks with no album (shown as 'misc' in Mars) An optional filename extension may be added to refine the search. /trackpath/PATH PATH is the absolute pathname of the file /trackplaying The track that is currently playing Returns 404, "Not Found" if no track is playing /list/NUMBER The nth item in the on screen playlist. NUMBER numbered from 0 GET /track/ARTIST/ALBUM/TRACK GET /tracknum/ARTIST/ALBUM/TRACKNUMBER GET /trackpath/PATH GET /trackplaying GET /list/NUMBER Content-Type: text/x-ini; charset=UTF-8 Dump of track's information in .ini format, UTF-8, CRLF line separated artist=Pink Floyd album=Dark Side of the Moon ; $MISC_ALBUM_NAME if has no album track=On The Run number=2 ; optional, not written if track does not have a number path=C:\Albums\Pink Floyd\Dark Side of the Moon\02 On The Run.mp3 rating=** ; optional, not written if no rating ; "", "", "", "" or "" damaged=true ; "true" or "false" year=1975 ; optional, not written if year unknown last-played=1975-09-24T12:34:56Z ; optional, not written if has never been played ; in ISO 8601 UTC format "YYYY-MM-DDTHH:MM:SSZ" alien=true ; optional, not written if track is part of the library local=false ; optional, not written if track is part of the local library remote=true ; optional, not written if track is not part of the remote user's library play=true ; optional, only written if track is playing pos=2.5 ; playback position in seconds ; optional, only written if track is playing length=545.2 ; the length of the track in seconds ; optional, only written if track is playing enqueue=true ; optional, only written if track is in playlist artist=Pink Floyd ; the name of the artist album=Dark Side of the Moon ; optional, not present for tracks without an album (misc) GET /track/ARTIST/ALBUM/TRACK/name GET /tracknum/ARTIST/ALBUM/TRACKNUMBER/name GET /trackpath/PATH/name GET /trackplaying/name GET /list/NUMBER/name the name of the track e.g. request /tracknum/Pink%20Floyd/The%20Dark%20Side%20of%20the%20Moon/2/name GET /track/ARTIST/ALBUM/TRACK/album GET /tracknum/ARTIST/ALBUM/TRACKNUMBER/album GET /trackpath/PATH/album GET /trackplaying/album GET /list/NUMBER/album the name of the album $MISC_ALBUM_NAME if there is no album GET /track/ARTIST/artist/TRACK/artist GET /tracknum/ARTIST/artist/TRACKNUMBER/artist GET /trackpath/PATH/artist GET /trackplaying/artist GET /list/NUMBER/artist the name of the artist GET /track/ARTIST/ALBUM/TRACK/number GET /tracknum/ARTIST/ALBUM/TRACKNUMBER/number GET /trackpath/PATH/number GET /trackplaying/number GET /list/NUMBER/number "" if no number GET /track/ARTIST/ALBUM/TRACK/path GET /tracknum/ARTIST/ALBUM/TRACKNUMBER/path GET /trackpath/PATH/path GET /trackplaying/path GET /list/NUMBER/path returns the absolute pathname of the file PUT /trackplaying/path Play the given track, specified by a path GET|PUT /trackplaying/pos Set the playback position of the playing song. Value in seconds, e.g "23.56" Can PUT "-" or "+" to adjust by an increment (5 sec) Can PUT "-n" or "+n" to adjust by the given number of seconds, e.g "+10.0" If the adjustment goes past the end of the song the next track will be played. If the adjustment goes to before the start of the song (< 0.0) the previous song will be played and skipped to the adjustment before the end. GET /trackplaying/length Get the length in seconds of the currently playing song. e.g. "305.5" GET|PUT /track/ARTIST/ALBUM/TRACK/rating GET|PUT /tracknum/ARTIST/ALBUM/TRACKNUMBER/rating GET|PUT /trackpath/PATH/rating GET|PUT /trackplaying/rating GET|PUT /list/NUMBER/rating "" if no rating, otherwise "", "", "", "" or "" GET|PUT /track/ARTIST/ALBUM/TRACK/damaged GET|PUT /tracknum/ARTIST/ALBUM/TRACKNUMBER/damaged GET|PUT /trackpath/PATH/damaged GET|PUT /trackplaying/damaged GET|PUT /list/NUMBER/damaged "true" or "false" GET|PUT /track/ARTIST/ALBUM/TRACK/last-played GET|PUT /tracknum/ARTIST/ALBUM/TRACKNUMBER/last-played GET|PUT /trackpath/PATH/last-played GET|PUT /trackplaying/last-played GET|PUT /list/NUMBER/last-played "" if never been played in ISO 8601 UTC format "YYYY-MM-DDTHH:MM:SSZ", e.g. "1975-09-24T12:34:56Z" GET|PUT /track/ARTIST/ALBUM/TRACK/play GET|PUT /tracknum/ARTIST/ALBUM/TRACKNUMBER/play GET|PUT /trackpath/PATH/play GET|PUT /trackplaying/play GET|PUT /list/NUMBER/play PUT "" or "true" to clear playlist and play the given track PUT "false" to stop playing if is playing GETs "true" if is playing else "false" GET|PUT /track/ARTIST/ALBUM/TRACK/playnow GET|PUT /tracknum/ARTIST/ALBUM/TRACKNUMBER/playnow GET|PUT /trackpath/PATH/playnow GET|PUT /trackplaying/playnow GET|PUT /list/NUMBER/playnow PUT "" or "true" to play the given track leaves the playlist intact PUT "false" to stop playing if is playing GETs "true" if is playing else "false" GET|PUT /track/ARTIST/ALBUM/TRACK/enqueue GET|PUT /tracknum/ARTIST/ALBUM/TRACKNUMBER/enqueue GET|PUT /trackpath/PATH/enqueue GET|PUT /trackplaying/enqueue GET|PUT /list/NUMBER/enqueue PUT "" or "true" to add track to playlist Plays if not playing PUT "false" to unenqueue GETs "true" if is in playlist else "false" ?play=true Will start playing the enqueue track if not playing. GET /track/ARTIST/ALBUM/TRACK/alien GET /tracknum/ARTIST/ALBUM/TRACKNUMBER/alien GET /trackpath/PATH/alien GET /trackplaying/alien GET /list/NUMBER/alien GET /trackplaying/alien "true" or "false" Returns true if track is not part of the library. GET /track/ARTIST/ALBUM/TRACK/local GET /tracknum/ARTIST/ALBUM/TRACKNUMBER/local GET /trackpath/PATH/local GET /trackplaying/local GET /list/NUMBER/local GET /trackplaying/local "true" or "false" Returns true if track file a accessable from the local computer GET /track/ARTIST/ALBUM/TRACK/remote GET /tracknum/ARTIST/ALBUM/TRACKNUMBER/remote GET /trackpath/PATH/remote GET /trackplaying/remote GET /list/NUMBER/remote GET /trackplaying/remote "true" or "false" Returns true if track is part of the remote users's collection GET /trackplaying/length The length of the file in seconds if it is playing. e.g. "23.5" "" if not playing Event Methods ============= PUT /notify "false" To cancel all notifications. PUT /notify/EVENT "true" or "false" The plugin will be informed when it GETs /event of the given event. e.g. PUT /notify/track-play PUT /notify/menu/MENU/NAME "true" or "false" Add a menu item to the given menu MENU, MENU is "file", "view", "tools", "help", "library" in the top menu bar, or "artist", "album" or "track" for their respectice right-click menus. The plugin will be informed when it GETs /event of the given event. e.g. PUT /notify/menu/library/View Stats PUT /notify/menu/MENU/NAME/enable "true" or "false" Enable or disable the given menu. PUT /notify/menu/library/View Stats/enable PUT /notify/menu/MENU/NAME/check "true" or "false" Check or un-check the given menu. PUT /notify/menu/library/View Stats/check GET /event Content-Type: text/x-ini; charset = UTF-8 returns "" if not events have occured since the last GET of /event All events begin with: event = EVENT e.g.: event = stop EVENT types ----------- play event = play The user has pressed play button. Play may be the result of unpausing. stop event = stop The user has pressed stop button. forward event = forward The user has pressed the skip forward button. pause event = pause The user has pressed the pause button. back event = back The user has pressed the skip back button. track-play event = track-play path = PATH A file has started to be played. PATH is the absolute path of file track-stop event = track-stop path = PATH A file has stopped being played. PATH is the absolute path of file mute event = mute mute = true the user has toggled the mute state mute us "true" or "false" volume event = volume volume = 0.666 the user has set the volume volume is from 0.0 to 1.0. current-user-changed event = current-user-changed name = USER display-user-changed event = display-user-changed name = USER menu event = menu type = TYPE name = NAME The use has selected the registered menu item. e.g. (from the notify/menu example above) event = menu type = library name = View Stats Configuration methods ===================== The extract values defined in the script tags and set by the user. GET /config Content-Type: text/x-ini; charset=UTF-8 Dump of plugins's configuration in .ini format, UTF-8, CRLF line separated host=ahost.com port=1234 user/general/name=fred user/general/password=derf user/me/name=myself smith user/me/name=agent smith GET /config/KEY # config/host = string; default="myhost.com" e.g. GET /config/host GET /config/user/USER/KEY # config/user/$USER/login = string e.g. GET /config/user/Fred/login User methods ============ GET /current-user Content-Type: text/x-ini; charset=UTF-8 Dump of the current user in .ini format, UTF-8, CRLF line separated name=general remote=false GET /current-user/name The name of the current user GET /current-user/remote Always "false" GET /display-user Content-Type: text/x-ini; charset=UTF-8 Dump of the current display user in .ini format, UTF-8, CRLF line separated name=general remote=true GET /display-user/name The name of the current user GET /display-user/remote "true" is the display user us a remote user, "false" otherwise GET /user/NAME Content-Type: text/x-ini; charset=UTF-8 Dump of the given user in .ini format, UTF-8, CRLF line separated name=a friend remote=true GET /user/NAME/name The name of the given user GET /user/NAME/remote "true" is the user NAME us a remote user, "false" otherwise Responses ========= 200 OK Accepted 404 Not Found The requested was valid but the data was not found, e.g. Unknown Artist 400 Bad Request The requested was invalid. The URL is not valid, e.g. /artist/Abba/width, where 'width' is not a valid field of an artist. 406 Invalid Value The requested was invalid. The value of the submitted data was invalid, e.g. "trux" when a boolean "true" or "false" was expected 415 Unsupported Media Type The requested was invalid. The type of data submitted was invalid, e.g. "image/jpeg" when "plain/text" was expected 500 Internal Server Error There was a malfunction inside Mars. This should never happen. Please report a bug. text/x-ini Content-Type ======================= This is the Windows 3 .ini file format. Mars always sends and receives in UTF-8 format with Internet/Windows line endings (CR LF) Example: ; comment key = value [section] key = value key = "a multi line\r\nvalue " sections must not contains the ], SPACE, TAB, or any control characters leading and trailing whitespace (SPACE or TAB) is ignored keys should only contain the characters 0-9, a-z, A-Z, _, - or Unicode above 128 key must not contain =, SPACE, TAB or any control characters, or begin with # ; or [ leading and trailing whitespace (SPACE and TAB) is ignored values leading and trailing whitespace (SPACE and TAB) is ignored if a value contains leading or trailing whitespace (SPACE or TABS), multiple lines or control characters (bytes 0 through 0x31) the string is enclosed in "double quotes" and special characters are escaped as per ANSI-C/C++/C#/Java/Python/Ruby: \a Bell (alert) (ASCII 7) \b Backspace (ASCII 8) \f Form feed (ASCII 12) \n New line (Line feed) (ASCII 13) \r Carriage return (ASCII 10) \t Horizontal tab (ASCII 9) \v Vertical tab (ASCII 11) \' Single quotation mark (ASCII 39) \" Double quotation mark (ASCII 34) \\ Backslash (ASCII 92) \ooo ASCII character in octal notation Up to 3 octal characters \xhh ASCII character in hexadecimal notation Unlike ANSI-C only up to two 2 hex characters Non ASCII UTF-8 bytes (0x80 to 0xFF) do not need to be escaped. When encoding multiple lines use Internet/Windows line endings "\r\n" keys and sections are case sensitive This differs from the Traditional Windows INI file in that: - the charset is UTF-8 rather than Latin-1/ISO 8859-1 - the \? escape seqeuence for ? is not supported (Not ANSI-C) - keys and sections are case sensitive - ; comments can not appear on a line Advocacy -------- INI files are simple for people and machines to read and write. INI vs XML XML is usually overkill + .ini easier for people to read and edit + .ini easier for programs to parse and write INI vs RFC822 (Email and Web headers): + .ini provides a two level heirarchy + .ini handles Unicode deficiecies: - only two level heirarchy keys and sections may contain . to provide a deeper heirarchy Plugin Command Syntax ===================== The command syntax is a subset of Unix .sh. This is tidier and more powerful that windows %VAR% substitutions and provides cross platform compatibility. Basically $VAR or ${VAR} expands an environment variable. \\ expands to \ so on Windows a path with \s must be written using \\ e.g "C:\\Albums\\Various" \$ expand to $ ${VAR} or $VAR error is $VAR not set ${VAR:-DEFAULT} DEFAULT if $VAR is not set or is "" ${VAR-DEFAULT} DEFAULT if $VAR is not set ${VAR:=DEFAULT} set $VAR to DEFAULT if $VAR is not set or is "" ${VAR=DEFAULT} set $VAR to DEFAULT if $VAR is not set ${VAR:?} error is $VAR is not set or is "" ${VAR:?DEFAULT} DEFAULT if $VAR is "" error is $VAR is not set ${VAR:+DEFAULT} error is $VAR is not set or is "" otherwise DEFAULT ${VAR+DEFAULT} error is $VAR is not set otherwise DEFAULT .martial Files ============== Martial files are simply one line containing the command and a number of optional comment lines specifiying the title and version etc.. example: # title = Google... "$BROWSER" "http://www.google.com/search?q=$ARTIST" See Plugin Command Syntax for the command line syntax. See Script tags for the tags syntax. Winamp Input Plugins ==================== Winamp input plugins are loaded if they are copied into the Plugins\ directory where Mars is installed. This will allow files to be played and, if the plugin supported it, tags to be editied. Hack to read metadata in old plugins ------------------------------------- Winamp input plugins did not always explicitly support reading or writing file tags. But many plugins allows the title format to be specified, this can be used to tell Mars about the tags in a file. Winamp input plugins are configured through the Options|Configuration, Plugins|Input screen, [Configure...] button. The title for Mars is on the form: For Mars::==... The delimiter can be multiple characters. keys are: title album album-artist artist track-number year genre comment e.g: The TAB character is a useful character to use as a delimiter as this will not appear in artist or album names etc.. To insert a TAB into a dialog box copy and paste it. For Mars: :track-number=%0 artist=%1 title=%2 album=%3 year=%4 genre=%6 For Mars:####:track-number=%0####artist=%1####title=%2####album=%3####year=%4####genre=%6