The Player

The player is the big money part of BAPS3, it's the bit that makes the noise, remembers what you want to play, and most importantly, the biggest part to screw up in difficult to trace ways. Here's a rundown of how it works.

General

The player is located in player.py.

A player provides the following functionality:

• Loads a singular audio file (currently only used for MP3 format) into memory at any given time.
• Allows playback, seeking and setting audio markers/cue points of the loaded item.
• Outputs audio to a single (stereo) sound card output.
• Triggers tracklisting API calls to make record of it's audio playout.
• Stores a "Show Plan" of the audio items (PlanItem) it can play.
• Provides a messaging protocol to control it/report it's status.

In the standard configuration, there are 3 concurrent instances of players. Each instance does not directly talk to other instances, they operate solely via the communication protocol using Python's MultiProcessing Queues.

As of writing, BAPSicle can support an arbitrary number of players via config option. WebStudio, the presenter UI, is not as easily configurable outside of 3 channels.

Communications

The player has a main loop, this checks for incoming command messages from the rest of BAPSicle. Each known command will return a response message informing the client if it was successful or not. See the following table of commands.

Command Format

The commands are almost a 1-1 mapping on functions in player.py. All commands except OUTPUT are only available when the player is correctly initialized.

The command message format is as follows, comprising of colon separated values. If a command has no extra fields, it is not required. The command should not end in a trailing colon.

SRC:COMMAND:EXTRAFIELDS

The player will respond with a message in the following format, which begins with the command message sent in, followed by a STATUS of either "OKAY" or "FAIL", depending on if the player accepted this command and performed the expected action.

SRC:COMMAND:EXTRAFIELDS:STATUS

Status Updates

The player also sends regular updates to clients, reporting its status. These are triggered whenever anything in the player's state changes, except when a state parameter is rate limited. JSON is the full player state represented {"foo":"bar"...}

ALL:STATUS:JSON

Position Updates

The player will also scream playback position (in float seconds) updates if the player is playing in the following format:

ALL:POS:0.0

Command Listing

Command	Extra Fields	Allowed When	Description
- Show Plan -	-	-	-
CLEAR	-	-	Removes all PlanItems from the Show Plan. Leaves the loaded item unaffected.
GET_PLAN	[PlanID] Str: The ID for the plan	-	The player should request from the API a show plan with the given ID. The Show Plan will be CLEARed, but the loaded item will not be affected.
LOAD	[Weight] Int: The PlanItem index in the show plan to load.	Not playing	Loads the item from the show plan list, ready for immediate playback. Applies SEEK to cue markers if present. See below.
ADD	[PlanItem] JSON: Representation of the PlanItem	-	Adds new PlanItem to the show plan list, in the position of the "weight" set in the PlanItem.
REMOVE	[Weight] Int: The PlanItem index	-	Removes the item with given weight from the show plan. Leaves the loaded item unaffected.
SETMARKER	[TimeslotItemId] Int: The id of the plan item to set markers on, [Marker] JSON: Representation of Marker	-	Adds/replaces a audio marker on the associated PlanItem with TimeslotItemId.
RESETPLAYED	[Weight] Int: The PlanItem index in the show plan to reset the play count of.	-	Resets the play counter of the item.
- Playback -	-	-	-
UNLOAD	-	Not playing	Releases any currently loaded PlanItem from RAM.
PLAY	-	Not playing	Start playing from the current audio position, effectively un-pausing the player.
UNPAUSE	-	Not playing	Same as PLAY.
PAUSE	-	Playing	The player stops playing audio, but remembers it's audio position for later resume.
PLAYPAUSE	-	Loaded	Same as PLAY if the player is not currently playing. Same as PAUSE if player is already playing.
STOP	-	Loaded	Stops audio playback, but also resets the audio position. See cue marker behaviour below.
SEEK	[Position] Float: Number of seconds in the file to move the audio position to.	Loaded	This will take effect if playing or not.
AUTOADVANCE	[Enabled] Bool ("True", "False"): The new setting for Auto Advance	-	Determines whether, on reaching the end of the current file, the player should automatically LOAD the next PlanItem weight in the show plan, or just STOP.
REPEAT	[Mode] RepeatMode ("all", "one", "none"): The new repeat setting.	-	Only applies when AUTOADVANCE Enabled, Determines whether, on advancing, the player loads all: the next PlanItem (wrapping from last PlanItem to first if at end of show plan), one: Commits a STOP (doesn't auto advance) none: Only when the end of playback of the last item is reached is a STOP performed, else auto advances.
PLAYONLOAD	[Enabled] Bool ("True", "False"): The new setting for Play On Load	-	Determines whether, on LOADing an item, it automatically PLAYs.

Notes

The Command Protocol has some inconsistencies, some of which are originally based on the implementation inside WebStudio. These should be resolved soon.