Media command processing

The mm-control service monitors its PPS control object constantly. When a client writes a command to this PPS object, mm-control checks the command syntax and if it's valid, invokes other multimedia services to perform the requested media operation. When these services report that the operation is complete, mm-control writes the operation's outcome to the same PPS object.

We recommend that any PPS-based service that you write to replace mm-control follow the procedure and design described here.

The mm-control service consists of a PPS communications layer and several subsystems that each manage a different set of media operations. When a client application writes a new command to the PPS control object, these mm-control components process the command by performing the following steps:

  1. Reading new PPS object content

    The read() system call returns the new content of the PPS control object to the mm-control service. The service's PPS layer searches this content for the msg and dat attributes; if either one is missing, the service logs an error and stops processing the command.
  2. Dispatching appropriate subsystem

    If the command written to PPS has the necessary attributes, mm-control reads the operation name stored in the msg attribute. The first word in the operation name refers to the command category, which must be one of the following:
    • output
    • zone
    • trksession
    • player
    The commands in each of these categories operate on different object types, as explained in mm-control components. Based on the command category, mm-control invokes the appropriate subsystem to examine the remaining words in the operation name.

    If the operation name doesn't begin with any of the four words listed above or if its remaining words don't refer to any action supported by the selected subsystem, mm-control logs an error and stops processing the command.
  3. Data and state validation

    The mm-control subsystem that's processing the command examines the dat attribute to verify that the client provided all the necessary data parameters, and then verifies that the parameter values and the current playback state are valid for the requested operation. For example, when issuing the "player_play" command, a client must provide a player name that matches one of the entries in the mm-control players list. Also, the playback state, which is also stored by mm-control, must be IDLE, PAUSED, or STOPPED.

    If the validity check for the data and the playback state fails, mm-control logs an error and stops processing the command.
  4. Invoking lower-level multimedia services

    The lower-level multimedia services aren't needed to carry out any commands in the output and zone categories; for these commands, mm-control skips this step.

    When processing trksession or player commands, mm-control either writes to PPS objects or makes API calls to invoke the lower-level multimedia services to carry out the requested media operation. For instance, in response to the "player_set_params" command, the player subsystem examines the type attribute found in the content read from the PPS control object. Based on this attribute's value (e.g., input, track), the subsystem then calls the mm-renderer API function that sets the specified type of parameters (e.g., mmr_input_parameters(), mmr_track_parameters()).

    For the full list of supported media commands, shown by category, see the /pps/services/mm-control/control entry in the PPS Objects Reference.
  5. Updating internal data structures

    The mm-control subsystem that processes the command checks the return codes of all API function calls. After each successful call, the subsystem updates the internal data structures as necessary. For example, the mmr_set_speed() returns 0 after the "player_set_speed" command has been successfully executed. In response, the player subsystem updates the speed setting in the data structure that holds information on the player indicated by the command's data.

    For commands that don't require using any lower-level multimedia services (e.g., "output_create" and "zone_attach_outputs", the relevant subsystem simply updates the lists of media resources available for playback, based on the requested operation.
  6. Reporting operation outcome

    The last command-processing activity done by mm-control is to write the outcome (result) of the media operation into the PPS control object.

    The operation name is echoed in the res attribute. Any data describing the new playback state is encoded in JSON format and stored in the data attribute; for instance, after executing the "player_next_track" command, mm-control reports the track ID, file ID, and URL for the newly selected (and now playing) track. The error code is written to the err attribute. If this code is 0, then no error has occurred. Otherwise, the errstr attribute contains a brief description of the error encountered.

    Clients can retrieve the results as soon as mm-control updates the PPS control object by using delta mode and blocking read() calls, identical to how mm-control reads this same PPS object.