Audio and Media Control Schema

From XAP Automation
Jump to: navigation, search

Audio and Media Control v2.2

This describes a collection of xAP message schema for use in Audio and Media control applications. These can be used to control networked MP3 receivers such as the Slim Devices SliMP3 or the Barix Exstreamer.

Change History

  • v2.0 20/04/03 First release with general audio/transport support rather than device specific.
  • v2.1 26/04/03 Slightly adjusted a few items throughout the whole schema.
  • v2.2 09/11/03 Added SliMP3.IR support

22/11/03 Added Jump command to Playlist.Track; Now.Playing block in Playlist.Event; PlayerPref

xap-header

Target=”Receiver name” e.g. “SlimDevices.SliMP3.Lounge” or “Barix.Exstreamer.Bedroom”

For example:

xap-header
{
v=12
hop=1
uid=FF1234??
class=[see classes below]
source=[whatever]
target=Barix.Exstreamer.Lounge
}

Generic Schema

Unless otherwise stated a name/value pair is assumed to be mandatory.

Where [.Event] is indicated a ‘sub-class’ ‘”inherits“ all the block types of the main class and these may occur as Event notifications using the same block layout. In cases where the Class.Event schema adds additional unique blocks these will be documented separately.

Class=xAP-Audio.Transport

These messages control the main transport interface. Missing are commands to shuffle and repeat. Whilst these are related to the transport mechanism, alongside play and stop, they alter the playlist and can be found there.

Audio.Transport
{
Command=[play | pause | stop | next | prev]
--- mandatory
Param=[on | off]
--- optional (depending on Command/Hardware support)
}

Notes:

  • If track is currently paused, play command should cause resumption of playing of current track ie unpause.
  • If track is currently paused, pause command should cause resumption of playing of current track ie a toggle.
  • Parameter value forces Pause state, regardless of current state ie absolute command rather than a toggle.


Audio.Seek
{
Seek=[+/-mm.ss | absolute mm.ss]
}

Class=xAP-Audio.Audio[.Event]

These may or may not be supported by the hardware e.g. Rio Receivers don’t support Mute apparently. The Slims don’t currently support balance/bass/treble. The Slim doesn’t appear to have explicit support for muting, but this could be achieved by recording the current volume perhaps.

Audio.Mute
{
Mute=[On | Off | Toggle]
}


Audio.Mixer
{
Volume=[0…100 | +nn | -nn]
--- optional
Balance=[-100…0…+100 | +nn | -nn]
--- optional
Bass=[0…100 | +nn | -nn]
--- optional
Treble=[0...100 | +nn | -nn]
--- optional
}

Class=xAP-Audio.Query

Audio.Query
{
Query=[mode | sleep | power | volume | balance | bass | treble]
}
Audio.Notification
{
Query=[mode | sleep | power | volume | balance | bass | treble]
Status=”Response suitable to query command”
}

Mode queries the current transport mode ie. Play, Stop, etc

Track.Query
{
Query=[time | genre | artist | album | title | duration | path]
}
Track.Notification
{
Query=[time | genre | artist | album | title | duration | path]
Status=”Response suitable to query command”
}


Playlist.Query
{
Query=[Index | Genre | Artist | Album | Title | Duration | Path | Tracks |  Shuffle | Repeat]
Index=”index in playlist”
--- optional (depending on query selected)
}
Playlist.Notification
{
Query=[Index | Genre | Artist | Album | Title | Duration | Path | Tracks |  Shuffle | Repeat]
Status=”Response suitable to query command”
Index=”index in playlist”
--- optional (depending on query selected)
}

Class=xAP-Audio.Schedule[.Event]

There could be a case for placing this in the xAP-Audio.Transport schema, but I can imagine this area could be developed in future for additional functionality; hence it has its own (minimal) schema for now.

Schedule.Sleep
{
Sleep=”time in seconds”
--- Controls the number of seconds to continue playing before powering off the  player
}

Class=xAP-Audio.Playlist

Playlist.Track
{
Command=[Play | Append | Delete | Index]
Track=[“TrackURL” | “TrackIndex”]
--- Play/Append use “TrackURL” whilst Delete/Index use “TrackIndex”
}
  • Play - puts the specified track URL into the current playlist and plays that track. Any tracks previously in the playlist are discarded,
  • Append – adds the specified track URL to end of the current playlist. Any tracks currently playing or already on the playlist are not affected.
  • Delete – deletes the track at the specified index from the current playlist.
  • Index – sets the track that is current playing by index. An absolute or relative index is valid i.e. “[+ | -]nnn”

Notes:

  • Track Index values are 0-based
Playlist.Move
{
From=”from index”
To=”to index”
}
Playlist.Edit
{
Edit=[Load | Add | Clear]
Playlist=”Playlist URL”
--- mandatory for Load and Add, otherwise Optional, Illegal or NotRequired
}
Playlist.Album
{
Command=[Load | Append]
--- mandatory
Genre=”genre”
--- mandatory
Artist=”artist”
--- mandatory
Album=”album”
--- optional – if not present, All albums are assumed ie “Album=*”
}

Repeat could possibly go in the xAP-Audio.Transport schema???

Playlist.Repeat
{
Repeat=[Stop | Track | Playlist]
}
  • Stop – stop at end of current playlist
  • Track – repeat current track indefinitely
  • Playlist – repeat current playlist indefinitely

Shuffle seems appropriate for xAP-Audio.Transport, but is placed here since it shuffles the Playlist.

Playlist.Shuffle
{
Shuffle=[On | Off]
}

Class=xAP-Audio.Playlist.Event

xAP-Audio.Playlist.Event ‘inherits’ the xAP-Audio.Playlist blocks and adds the following.

Now.Playing may be sent out whenever a change is detected in the current playlist track or at some other interval. It details the current track. Additionally a Now.Playing message may be sent when a new playlist is loaded. Some values will be missing in this case (e.g. Index and Title, as well as Path) and others may optionally be set to ‘*’.

Now.Playing
{
Title=”title”
--- mandatory (may be empty if data is unavailable)
Artist=”artist”
--- mandatory (may be empty if data is unavailable)
Album=”album”
--- mandatory (may be empty if data is unavailable) 
Path=”path to current track”
--- optional
Duration=”title duration”
--- optional
Index=”playlist index”
--- optional
Tracks=”number of tracks in the current playlist”
--- optional (Index and Tracks combine to indicate this is the nth of Y tracks)
Genre=”genre”
--- optional
}

SliMP3 Extensions

Class=SliMP3.Transport

Extensions to the SliMP3 transport mechanism. These include the ability to turn the Slim on or off.

SliMP3.Transport
{
Command=[off | on]
}

Class=SliMP3.Server

This is used to issue a server command. There is currently only a command to have the SliMP3 server rescan its music library, reloading the music file information.

Server.Command
{
Command=[rescan]
}

We can query the number, name and addresses of each of the SliMP3s in the system.

Player.Query
{
Command=[count | name | address]
PlayerIndex="nth player in the system"
--- mandatory for “name” and “address”, ignored for “count”
}
Player.Notification
{
Command=[count | name | address]
PlayerIndex="nth player in the system"
--- Mandatory for “name” and “address”, ignored for “count”
Status="Response of command e.g. '192.168.1.231:3483"
}

The Pref commands allow the caller to set and query the SLiMP3 server’s internal preference values. Both result in a Pref.Notification message being sent in response.

Pref.Query
{
Pref=”SliMP3 Server internal preference value name e.g. ‘mp3dir’”
}
Pref.Set
{
Pref=”SliMP3 Server internal preference value name e.g. ‘mp3dir’”
Value=“value to set”
}
Pref.Notification
{
Pref=”SliMP3 Server internal preference value name e.g. ‘mp3dir’”
Status=”Current preference value for the requested preference”
}

The PlayerPref commands allow the caller to set and query the SLiMP3 server’s player-specific internal preference values. Both result in a PlayerPref.Notification message being sent in response.

  • doublesize (1 or 0)
  • powerOnBrightness (Dark, Dim, Bright, Brighter, Brightest)
  • powerOffBrightness (Dark, Dim, Bright, Brighter, Brightest)
PlayerPref.Query
{
Pref=”SliMP3 Server internal player-specific preference value name e.g. ‘doublesize’”
}
PlayerPref.Set
{
Pref=”SliMP3 Server internal player-specific preference value name e.g. ‘doublesize’”
Value=“value to set”
}
PlayerPref.Notification
{
Pref=”SliMP3 Server internal player-specific preference value name e.g. ‘doublesize’”
Status=”Current preference value for the requested preference”
}

Class=xAP-OSD.Display

Display.SliMP3
{
Line1="Text to display"
--- Mandatory
Line2="Text to display"
--- Mandatory
Duration="Duration to display in seconds"
--- Mandatory 
Align1=[Left | Centre | Right]
--- Optional (Left alignment is assumed if not present)
Align2=[Left | Centre | Right]
--- Optional (Left alignment is assumed if not present)
}

Notes:

  • Alignment can be adjusted by including spaces in the text to be displayed.
  • The Alignment setting just gets the display software to do the work in one place rather than in every application that uses this. It additionally decouples the code from the exact dimensions of the display.

Class=SliMP3.Display

Put display query messages into a SliMP3 specific extension class rather than in xAP-OSD.Display.

Display.Query
{
--- Deliberately empty - Can’t think of any suitable content
}
Display.Notification
{
Line1="Text being display"
Line2="Text being display"
}

Class=SliMP3.Button

Button.Command
{
Button=”button command”
--- Mandatory (see CLI documentation for list)
}
Button.Notification
{
Button=”button pressed on remote”
--- Mandatory (see CLI documentation for list)
}

Class=SliMP3.Event

IR.Event
{
Name=number_scroll_1
--- Optional
Code=0000f786
--- Mandatory
Time=1246.046408
--- Mandatory
}
Button.Event
{
Button=”button pressed on remote” e.g. “buttonScroll_1”
--- Mandatory (see CLI documentation for list)
}


Display.Event
{
Line1=”Text being displayed on Line1”
--- Mandatory
Line2=”Text being displayed on Line2”
--- Mandatory
Duration=”Length of display event in seconds”
--- Mandatory
}