Description

Messages are sent from WifiRemote to the client. Some messages are sent to all connected clients, some are only sent to specific clients that requested the information.

List of Messages

Welcome

The welcome message is sent to every client (socket) that connects to WifiRemoteDotNetAsyncSocketZeroConfigNetServicesJson.NET by James Newton-KingmartinvanderbooniPimp project?. It contains information about the plugin and about the current status of MediaPortal.

Fields

• Type (string): Type of the message, always "welcome"
• Server_Version? (int): Version of the server. A client can require a certain version of the server, to make sure all required features are supported by the plugin. We currently are at version 8
• AuthMethod (int): Authentication method needed to[ identify|Commands#identify] against to connect to this server. 0: None, 1: Username & Password (userpass), 2: Passcode, 3: Both (userpass and passcode) (introduced with api version 4)
• Status (object): This field contains a Status message. See below. (removed with api version 3)
• Volume (object): This field contains a Volume message. See below. (removed with api version 3)
• MPExtendedServicesInstalled (dictionary <string, bool>): flags if the mp-extended services MAS, TAS and WSS are installed on the HTPC (introduced with api version 10)
• TvPluginInstalled (bool): True if the client where WifiRemote is running also has the TV plugin installed. Useful if you want to hide TV stuff in your client when the user doesn't have the TV part installed. (introduced with api version 16)

Example:

{
    "Type":"welcome",
    "Server_Version":10,
    "AuthMethod":1,
    "MPExtendedServicesInstalled":
        {
            "MAS":true,
            "TAS":false,
            "WSS":true
        },
    "TvPluginInstalled":true
}

Server_Version (api version) mapping to WifiRemote release versions

• Server version 8 --> WifiRemote 0.4
• Server version 9 --> WifiRemote 0.5
• Server version 10 --> Wifiremote 0.6
• Server version 11 --> WifiRemote 0.6.1
• Server version 12 --> WifiRemote 0.7
• Server version 14 --> WifiRemote 0.8
• Server version 15 --> WifiRemote 0.8.1
• Server version 16 --> WifiRemote 0.8.2.1

Authentication Response

A client can send an authentication request to WifiRemote. Depending on the configured auth method this request will contain a username and password (auth method 'userpass'), a passcode (auth type 'passcode') or it won't be necessary (auth type 'none').

After receiving the request (or in case of auth type 'none' after sending the welcome message) WifiRemote will respond with an 'authenticationresponse' message. This message will tell the client if the authentication was successful or not.

Clients can only issue commands to WifiRemote and receive status and other messages from WifiRemote after they have been authenticated.

After receiving the authenticationresponse a client can consider itself fully connected to WifiRemote. If the auth type is 'none' the authentication response will always be positive and immediately sent.

new Autologin is a feature designed for clients that can't keep the connection open all the time. It has to be enabled in WifiRemote configuration. When it is enabled an autologin key will be sent on successful authentication. Every command containing this key (as parameter "AutologinKey") will be accepted for x minutes (defined in configuration), even if the client disconnected and reconnected inbetween without sending an identify message.

Please have a look at the demo client for an example on how to implement this feature.

After the connection has been established and the client was successfully authenticated WifiRemote will send the current status in form of a Status message, a Volume message and since API version 13 a FacadeInfo message.

Fields

• Type (string): Type of the message, always "authenticationresponse"
• Success (bool): True if the client was authenticated, false otherwise
• ErrorMessage (string): A message containing an error description when Success was false
• AutologinKey (string): A key that can be used to skip authentication for x minutes (introduced with api version 5)

Example

{
    "Type":"authenticationresponse",
    "Success":false,
    "ErrorMessage":"Login failed",
    "AutologinKey":"abde1230a0fafe653458bb"
}

Status

Describes the current status of MediaPortal, consisting of player and navigation related information. This is sent when the status changes (a file starts/stops playing, the user navigates in MediaPortal) and integrated in the welcome message.

Fields

• Type (string): Type of the message, always "status"
• IsPlaying? (boolean): true if MediaPortal is playing a file, false otherwise
• IsPaused? (boolean): true if MediaPortal is playing a file but it is paused, false otherwise
• IsPlayerOnTop (boolean): true if MediaPortal is playing in fullscreen but false if a dialog or menu is on top (introduced with api version 8)
• Title (string): Title of the currently played media file (for example "Hot Fuzz")
• CurrentModule? (string): Currently active module (for example "TV Series")
• SelectedItem? (string): Selected item in the skin. This is working a bit flaky at the moment. (for example: "Switch view")

Example:

{
  "Type":"status",
  "IsPlaying":false,
  "IsPaused":false,
  "IsPlayerOnTop":false,
  "Title":"",
  "CurrentModule":"Homescreen",
  "SelectedItem":"Music"
}

Volume

A message containing information about MediaPortals? volume. This is sent when there was a change in volume and integrated in the welcome message.

Fields

• Type (string): Type of the message, always "volume"
• Volume (int): Volume set in MediaPortal in percent (0 - 100)
• IsMuted? (boolean): true if the sound in MediaPortal is muted, false otherwise

Example:

{
  "Type":"volume",
  "Volume":100,
  "IsMuted":false"
}

Plugins

The plugins message is sent in response to a 'plugins' message. It contains a list of all installed and active window plugins in MediaPortal including the plugin name, the icon as byte array (if requested) and the window id of the plugin

Fields

• Type (string): Type of the message, always "plugins"
• Plugins (array): An array, containing one object per plugin with these fields:
  • Name (string): Name of the plugin in the same language as configured in MediaPortal
  • WindowId? (int): Window ID of the plugin. This can be used to activate the plugin via the window message.
  • Icon (string, optional): This string is a byte-array representation of the plugin icon png file. In the example it is cut to see what's going on. In your client you can get the image from this string and display it.
    This will be null if you didn't request plugin icons with your 'plugins' command

Example:

{
  "Type":"plugins",
  "Plugins":[
    {
      "Name":"Play Disc",
      "WindowId":3001,
      "Icon":"iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAMAAAD04JH5AAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAMAUExURQAAAAgHBwsLCxgYGCYmJjAvMDc3N0pJSlBPUFZVVmloaXh4eImJiZaWlpmsvpqytJuwvZ+5sZ+4vaSjpKqkqaurq6+rsKS7rqq8pqm8qqa0vaO5s6C4u6q3uai5vLGqr7yvq7OnsrKrsrqsu7K9pr60q7u/pL64rbOys7W8tLW+vLy2s7qzur65tL29vZurwpuzwaOrxauqw6C3yaW+xqa7z6y0xK+5xaa60au61LSswrqtw7O1xLS7wbq0wry0zL2+wLC917S82Lu51Li82KXAqqvBpqrAq6bBvarEu63KuLLDpLLDrbfIpbDJrbvDpLvEq7/LpL3Lq7..."
    },
    {
      "Name":"Moving Pictures",
      "WindowId":12345,
      "Icon":"..."
    }
  ]
}

Properties

This message is sent in response to a "properties" request message. It contains the properties (tag and value) of all requested tags. Furthermore, from now on the client will be notified if one of the requested properties changes with a propertychanged message. Only properties that start with #Play or #TV.View are currently supported. See for a list of supported tags.

Fields

• Type (string): Type of the message, always "plugins"
• Tags (array): An array, containing one object per plugin with these fields:
  • Tag (string): Name of the property
  • Value (string): Value of the property.

Propertychanged

The propertychanged message is sent when one of the tags changes, to which the client has registered for with the properties message.

Fields

• Type (string): Type of the message, always "plugins"
• Tag (string): Name of the property
• Value (string): Value of the property.

Nowplaying

A nowplaying message is sent to all connected clients when playback of a supported file starts. This message contains information about the file, taken from the corresponding plugins like MP-TVSeries or Moving Pictures. Due to the differences in the plugins the content of the nowplaying message can vary.

Fields (global)

• Type (string): Type of the message, always "nowplaying"
• Duration (int): Duration of the file in seconds
• Position (int): Current position in the file in seconds
• File (string): Path of the file
• IsTv (bool): Is the now playing item tv?
• IsFullscreen (bool): Is the player in fullscreen mode? (introduced with api version 5)
• MediaInfofile tags? (object): An object containing media specific information. You can check which type of information it is with the MediaInfo? field "MediaType?".

Fields (series)

• MediaType? (string): Type of MediaInfo?, for series always "series"
• SeriesId (int): ID of the series, matching that in MP-TVSeries' database (introduced with api version 8)
• SeasonId (int): ID of the season, matching that in MP-TVSeries' database (introduced with api version 8)
• EpisodeId (int): ID of the episode, matching that in MP-TVSeries' database (introduced with api version 8)
• Series (string): Name of the series
• Season (int): Season of this episode
• Episode (int): Number of this episode in the season
• Title (string): Name of the episode
• AirDate? (string): First air date of the episode
• Director (string): Director(s) of the episode
• Writer (string): Writer(s) of the episode
• Genre (string): Genre(s) of the series
• Image (string): byte-array representation of the season poster image. You can initialize an image from this string in your client. The string is cut in the example (removed with api version 4)
• ImageName (string): Path and filename of the season poster image. Request image data via image command (introduced with api version 4)
• MyRating? (string): Rating the user gave this episode
• Plot (string): Plot description of this episode
• Rating (string): Online rating of this episode
• RatingCount? (string): Number of votes this episode got online
• Status (string): Status of the series. Can be "Continuing" and "Ended".

Example (series)

{
    "Type":"nowplaying",
    "Duration":2458,
    "Position":0,
    "IsTv":false,
    "IsFullscreen":true,
    "File":"",
    "MediaInfo":{
        "MediaType":"series",
        "SeriesId":76290,
        "SeasonId":10063,
        "EpisodeId":189255,
        "Series":"24",
        "Season":1,
        "Episode":1,
        "Title":"Tag 1: 00:00Uhr-01:00Uhr",
        "AirDate":"2001-11-06",
        "Director":"Stephen Hopkins",
        "Writer":"Robert Cochran, Joel Surnow",
        "Genre":"|Action and Adventure|Drama|",
        "ImageName":"c:\images\series\24.jpg",
        "MyRating":"",
        "Plot":"Stressiger Abend f\U00fcr CTU-Agent Jack Bauer: Seine halbw\U00fcchsige Tochter Kimberly stiehlt sich unerlaubt aus dem Haus. Aber bevor er sich auf die Suche machen kann, wird er dringend ins B\U00fcro zitiert, denn Terroristen planen einen Anschlag auf Senator David Palmer. Es scheint eine lange Nacht f\U00fcr den Agenten zu werden...",
        "Rating":"7.5",
        "RatingCount":"",
        "Status":"Ended"
    }
}

Fields (moving-pictures)

• MediaType? (string): Type of MediaInfo?, for moving-pictures always "movies"
• ItemId (int): ID of the movie in Moving Pictures' movie_info database table (introduced with api version 8)
• Title (string): Name of the movie
• AlternateTitles? (string, pipe | separated): Alternate names of the movie (foreign names)
• Tagline (string): Tagline of the movie
• Year (int): Release year of the movie
• Directors (string, pipe | separated): Directors of the movie
• Writers (string, pipe | separated): Writers of the movie
• Actors (string, pipe | separated): List of actors in the movie
• Genres (string, pipe | separated): Genre(s) of the movie
• Certification (string): Certification of the movie
• DetailsUrl? (string): URL to a website where the movie information was scraped from
• Image (string): Byte-array representation of the movie poster image. You can initialize an image from this string in your client. The string is cut in the example (removed with api version 4)
• ImageName (string): Movie poster image path and filename. Request image data via image command (introduced with api version 4)
• Rating (string): Online rating of the movie
• Summary (string): Movie summary

Example (moving-pictures)

{
    "Type":"nowplaying",
    "Duration":7177,
    "Position":0,
    "File":"";
    "MediaInfo":{
        "MediaType":"movie",
        "ItemId":12,
        "Title":"Star Wars",
        "AlternateTitles":"|La guerra de las galaxias|La guerre des \U00e9toiles|",
        "Tagline":"It's Back! (re-release)",
        "Year":1977,
        "Directors":"|George Lucas|",
        "Writers":"|George Lucas|",
        "Actors":"|Mark Hamill|Harrison Ford|Carrie Fisher|Peter Cushing|Alec Guinness|Anthony Daniels|Kenny Baker|Peter Mayhew|David Prowse|James Earl Jones|",
        "Genres":"|Action|Adventure|Fantasy|Sci-Fi|",
        "Certification":"PG",
        "DetailsUrl":"http://www.imdb.com/title/tt0076759",
        "Image":"/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKD...",
        "Rating":"8,8",
        "Summary":"Part IV in a George Lucas epic, Star Wars: A New Hope opens with a rebel ship being boarded by the tyrannical Darth Vader. The plot then follows the life of a simple farmboy, Luke Skywalker, as he and his newly met allies (Han Solo, Chewbacca, Ben Kenobi, C-3PO, R2-D2) attempt to rescue a rebel leader, Princess Leia, from the clutches of the Empire. The conclusion is culminated as the Rebels, including Skywalker and flying ace Wedge Antilles make an attack on the Empires most powerful and ominous weapon, the Death Star."
    }
}

Fields (MyVideos)

• MediaType? (string): Type of MediaInfo, for MyVideos always "video"
• ItemId (int): ID of the video in MyVideos' database (introduced with api version 8)
• Title (string): Name of the movie
• Tagline (string): Tagline of the movie
• Year (int): Release year of the movie
• Directors (string, pipe | separated): Directors of the movie
• Writers (string, pipe | separated): Writers of the movie
• Actors (string, pipe | separated): List of actors in the movie
• Genres (string, pipe | separated): Genre(s) of the movie
• Certification (string): Certification of the movie
• ImageUrl (string): Movie poster URL. Request image data via HTTP (introduced with Server_Version 4)
• Rating (string): Online rating of the movie
• Summary (string): Movie summary

Example (MyVideos)

{
    "Type":"nowplaying",
    "Duration":7177,
    "Position":0,
    "File":"";
    "MediaInfo":{
        "MediaType":"video",
        "ItemId":16,
        "Title":"Star Wars",
        "Tagline":"It's Back! (re-release)",
        "Year":1977,
        "Directors":"George Lucas",
        "Writers":"George Lucas",
        "Actors":"Mark Hamill Harrison Ford Carrie Fisher Peter Cushing Alec Guinness Anthony Daniels Kenny Baker Peter Mayhew David Prowse James Earl Jones",
        "Genres":"Action Adventure Fantasy Sci-Fi",
        "Certification":"13",
        "ImageUrl":"http://www.impawards.com/starwars/poster.jpg",
        "Rating":"8,8",
        "Summary":"Part IV in a George Lucas epic, Star Wars: A New Hope opens with a rebel ship being boarded by the tyrannical Darth Vader. The plot then follows the life of a simple farmboy, Luke Skywalker, as he and his newly met allies (Han Solo, Chewbacca, Ben Kenobi, C-3PO, R2-D2) attempt to rescue a rebel leader, Princess Leia, from the clutches of the Empire. The conclusion is culminated as the Rebels, including Skywalker and flying ace Wedge Antilles make an attack on the Empires most powerful and ominous weapon, the Death Star."
    }
}

Fields (TV)

• MediaType? (string): Type of MediaInfo?, for series always "tv"
• ChannelId (int): ID of the current channel
• ChannelName (string): Name of the current channel
• CurrentProgramId (int): ID of the current program
• CurrentProgramName (string): Name of the current program
• CurrentProgramDescription (string): Description of the current program
• CurrentProgramBegin (DateTime): Start date of the current program
• CurrentProgramEnd (DateTime): End date of the current program
• NextProgramId (int): ID of the next program
• NextProgramName (string): Name of the nextprogram
• NextProgramDescription (string): Description of the nextprogram
• NextProgramBegin (DateTime): Start date of the nextprogram
• NextProgramEnd (DateTime): End date of the nextprogram

Nowplayingupdate

A nowplayingupdate message is sent to all connected clients in fixed intervals during playback of a media item. This message contains information about the current playing state (duration, position, speed,...). It is meant to update a representation of the playback state on the remote end.

Fields

• Type (string): Type of the message, always "nowplayingupdate "
• Duration (int): Duration of the file in seconds
• Position (int): Current position in the file in seconds
• Speed (int): Current speed of the player
• IsTv? (bool): True if the currently playing item is a tv stream.
• IsFullscreen (bool): True if the player is in fullscreen mode (introduced with api version 5)

Example:

{
    "Type":"nowplayingupdate",
    "Duration":7177,
    "Position":40,
    "Speed":1,
    "IsTv":true,
    "IsFullscreen":true
}

Image

This messages contains an image requested via the image command. The image is a base64 encoded byte array.

Fields

• Type (string): Type of the message, always "image"
• ImagePath (string): Path of the image
• Image (byte[]): Base64 encoded byte array representation of the image
• UserTag (string): A user defined identifier to connect this response to an image command. (introduced with api version 7)

Example

{
    "Type":"image",
    "ImagePath":"C:\images\example.jpg",
    "Image":"/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKD...",
    "UserTag":"MusicCover"
}

Onscreenkeyboard

Notifies the client when the on-screen Mediaportal keyboard is shown or hidden. This would for example allow the client to show or activate its own keyboard for text-entry to Mediaportal and hide it when no longer required.

Fields

• Type (string): Type of the message, always "onscreenkeyboard"
• IsActive (boolean): True if the keyboard is opened, false if it is closed

Example

{
    "Type":"onscreenkeyboard",
    "IsActive":true
}

Facadeinfo

Provides meta-information about the currently active facade (a MediaPortal control that displays collections, for example a movie list).
You can send the Facade command with an action of "Get" to WifiRemote to get detailed information about this facade in form of a Facade message.

Fields

• Type (string): Type of the message, always "facadeinfo"
• SelectedIndex (int): Selected index of facacde
• Count (int): Item count of facade
• Visible (boolean): Is the facade visible to the user
• ViewType(string): Currently shown view of the facade (e.g. list, thumb, ...) (introduced with api version 13)

Facade

Provides information and all items of the current facade

Fields

• Type (string): Type of the message, always "facadeinfo"
• ViewType(string): Currently shown view of the facade (e.g. list, thumb, ...)
• WindowId (int): Id of the window where the facade is shown
• FacadeItems (List<FacadeItem>): List of all items in this playlist
  • [
    • FacadeItem -> Label (string): Label 1 of item
    • FacadeItem -> Label2 (string): Label 2 of item
    • FacadeItem -> Label3 (string): Label 3of item
  • ]

Dialog

Provides information and all items of the current facade

Fields

• Type (string): Type of the message, always "dialog"
• DialogShown (bool): Dialog state (shown, closed)
• Dialog (MpDialog): Dialog data (only sent when dialog state == shown)
  • MpDialog -> Heading(string): Dialog Heading
  • MpDialog -> DialogText(string): Text of dialog
  • MpDialog -> DialogType (string): Dialog Module name in MediaPortal (language dependant)
  • MpDialog -> DialogId(string): Id of Dialog
  • MpDialog -> AvailableActions(List<string>): Actions available for this dialog, these can be sent in the Dialog command to invoke actions on the dialog (e.g. get, setselected, ok, cancel, ...)

Screenshot

 (introduced with api version 14)

A message containing a screenshot requested with the screenshot command or an error if taking the screenshot failed.

Fields

• Type (string): Type of the message, always "screenshot"
• Screenshot (string): The image as a base64 encoded byte array in JPG format or null if an error occured
• Error (Dictionary): null if everything went fine, otherwise contains the following subnodes:
  • ErrorCode (int): A unique code representing one error message
  • ErrorMessage (string): A human readable error message in english describing the error. If an error occured you can always find more detailed information about it in the MediaPortal.log file when MediaPortal was set to debug logging.
    Error codes and messages are:
    • 10 - Could not watch for MediaPortal screenshots.
    • 11 - Error starting to watch for MediaPortal screenshots.
    • 20 - Could not create screenshot directory.
    • 30 - Timeout while waiting for MediaPortal to take the screenshot.
    • 40 - Could not read MediaPortal screenshot.
    • 0 - An unexpected error occured.

Example:

{
  "Type":"screenshot",
  "Screenshot":"asdQWDQwsdqwd[...]",
  "Error":null
}

// with error
{
    "Type":"screenshot",
    "Screenshot":null,
    "Error":{
        "ErrorCode":10,
        "ErrorMessage":"Could not watch for MediaPortal screenshots."?
    }
}