MME Playback Events

MME events are like other QNX Neutrino events. They are signals or pulses used to notify a client application thread that a particular condition has occurred. Unlike signals and pulses, events can be used to carry data.

This chapter includes:

For other information about other types of MME events, see the following chapters in this reference:

For more information about events in general, see the QNX Neutrino Programmer's Guide.

Playback events

The MME delivers playback events (MME_EVENT_CLASS_PLAY) to the client application to indicate the status or result of a playback activity.

The MME playback events are:

MME_EVENT_DVD_STATUS

The MME delivers the event MME_EVENT_DVD_STATUS when there are changes to the status of a DVD playback. These changes can be to a DVD:

Event data

The DVD status, in mm_dvd_status_event_t.

Database tables updated

No database tables are updated.

MME_EVENT_FINISHED

The MME delivers the event MME_EVENT_FINISHED when it has finished playing a track session and repeat mode is turned off so that no other playback will occur automatically.

Event data

The ID of the track session, in a uint64_t.

Database tables updated

The following tables are updated:

MME_EVENT_FINISHED_WITH_ERROR

The MME delivers the event MME_EVENT_FINISHED_WITH_ERROR when it has consecutively failed to initiate playback of the number of tracks defined by the <ConsecutivePlayErrorsBeforeStop> configuration element. It delivers this event to indicate that the current track session is not playable, and that it requires input from the client application to continue.

When the client application receives an MME_EVENT_FINISHED_WITH_ERROR event, it should assume that the current track session can't be played to completion, and take appropriate action. It may choose to call mme_next() to attempt playing another track in the track session, to create a new track session, to request input from the user, or to perform some other recovery task.


Note: The MME_EVENT_FINISHED_WITH_ERROR event is delivered to indicate that the MME was unable to initiate playback of several consecutive tracks in a track session, and that, therefore, the tracks in the track session are probably not readable — they may be corrupt, in an unsupported format, etc. Once playback has started, read errors are handled by io-media. See the MME Developer's Guide chapter Playback Errors.

Event data

The ID of the track session, in a uint64_t.

Database tables updated

The following table is updated:

MME_EVENT_MEDIA_STATUS

The MME delivers the event MME_EVENT_MEDIA_STATUS to indicate a change in the status of media playback. Delivery of this event is triggered by a change to any of the following:


Note:

At present, this event is delivered only:

  • for iPod devices
  • when a chapter changes (mm_media_status_reason_t = MM_MEDIA_CHAPTER_UPDATE)

Event data

Media status information, and the reason for delivery of the event, in mm_media_status_event_t.

Database tables updated

No database tables are updated.

MME_EVENT_NEWOUTPUT

The MME delivers the event MME_EVENT_NEWOUTPUT when it has detected a new output device in the system. The device can then be attached to a zone. If the device is already part of a zone that is currently being used for playback, the MME will automatically attach the new device to that zone.

Event data

The ID of the new output device, in a uint64_t.

The following table is updated:

MME_EVENT_NOWPLAYING_METADATA

The MME delivers the event MME_EVENT_NOWPLAYING_METADATA when it is playing a track and has updated metadata in the nowplaying table. This behavior means that the MME delivers:

After receiving a MME_EVENT_NOWPLAYING_METADATA, the client application should query the nowplaying table for new metadata.

In most cases the client application will receive a MME_EVENT_NOWPLAYING_METADATA event immediately after receiving a MME_EVENT_TRACKCHANGE event. There are, however, two exceptions to this rule:

Event data

No data is delivered.

Database tables updated

The following table is updated:

MME_EVENT_OUTPUTATTRCHANGE

The MME delivers the event MME_EVENT_OUTPUTATTRCHANGE when any output attribute changes.

Event data

The ID of the output where the change occured, in a uint64_t.

Database tables updated

No database tables are updated.

MME_EVENT_OUTPUTREMOVED

The MME delivers the event MME_EVENT_OUTPUTREMOVED when it detects that an output device has been removed. If the removed output device is the only active one on a zone where playback is underway, the MME will stop playback.

Event data

The ID of the removed output device, in a uint64_t.

Database tables updated

The following table is updated:

MME_EVENT_PLAYAUTOPAUSED

The MME delivers the event MME_EVENT_PLAYAUTOPAUSED after it has started playing a paused track. When it delivers this event, the MME is waiting for the client application to call the function mme_play_set_speed() with speed set to 1000 in order to begin playback of the track.

Event data

No data.

Database tables updated

No database tables are updated.

MME_EVENT_PLAY_ERROR

The MME delivers the event MME_EVENT_PLAY_ERROR when a playback error has occurred. Various playback errors trigger delivery of this event. The cause of the error is carried in the event data.

Event data

The cause of the error and the offset in mme_play_error_t.

Database tables updated

The database tables updated depends on the error that triggers delivery of the event.

MME_EVENT_PLAYLIST

For future use.

MME_EVENT_PLAYSTATE

The MME delivers the event MME_EVENT_PLAYSTATE when it changes the play state or the play speed in the control context. The play state is the type of playback underway in the control context. Examples of play states are playing, paused, seek to time, stopped, slow forward, fast forward, slow reverse and fast reverse.

This event is not delivered when playback changes tracks unless the play state or play speed have changed.

Event data

The current playstate and speed, in mme_playstate_speed_t.

Database tables updated

No database tables are updated.

MME_EVENT_PLAY_WARNING

The MME delivers the playback event MME_EVENT_PLAY_WARNING when io-media has indicated that it has detected a playback situation that requires a warning to the client application. The MME delivers this event if during playback of a file that is being ripped (or copied) io-media, due to fast forward or some other mechanism, playback advances so far that it risks over-running the end of the partially ripped file.

When the client application receives a MME_EVENT_PLAY_WARNING event, it should check the flags carried in the data structure mm_warning_info_t to determine the best course of action to take.

The first MME_EVENT_PLAY_WARNING event has mm_warning_info_t.mm_warning set to MM_WARNING_READ_TIMEOUT, indicating that playback is about to over-run the end of the ripped file, and that the client application can respond before playback reaches the end of the ripped file and the user hears a gap in the playback. Subsequent MME_EVENT_PLAY_WARNING events have mm_warning_info_t.flags set to MM_WARNING_FLAG_AUDIBLE, indicating that the user has encountered an audible gap in the playback.

Event data

mm_warning_info_t, with the appropriate warning flags set.

Database table updated

No database tables are updated.

MME_EVENT_RANDOMCHANGE

The MME delivers the event MME_EVENT_RANDOMCHANGE after it has changed the random play settings for a specified control context, or because a new track session has been set for the control context.

To find out the current random play mode for a control context, call the function mme_getrandom(). To change the random play mode of a control context, call the function mme_setrandom(). For more information about random mode settings, see mme_setrandom().


Note: The track number in a track session is determined differently in random playback and sequential playback modes. Therefore, if a client application receives the event MME_EVENT_RANDOMCHANGE it should call the function mme_trksession_get_info() to refresh its track number information.

Event data

The new random setting for the control context in mme_mode_random_t.

Database tables updated

The following tables are updated:

MME_EVENT_REPEATCHANGE

The MME delivers the event MME_EVENT_REPEATCHANGE after it has changed the repeat play settings for a specified control context, or because a new track session has been set for the control context. To find out the current repeat play mode for a control context, call the function mme_getrepeat(). To change the repeat play mode of a control context, call the function mme_setrepeat(). For more information about repeat mode settings, see mme_setrepeat().

Event data

The new repeat setting for the control context, in mme_mode_repeat_t.

Database tables updated

The following tables are updated:

MME_EVENT_SCANMODECHANGE

The MME delivers the event MME_EVENT_SCANMODECHANGE after it has changed the scan mode for a specified control context. To find out the current scan mode for a control context, call the function mme_getscanmode() to get the new setting. To change the scan mode for a control context, call the function mme_setscanmode().

Event data

No data.

Database tables updated

No database tables are updated.

MME_EVENT_TIME

A specified amount of time has passed during playback of a track.

Event data

A snapshot of current time information, in mme_time_t.

Database tables updated

No database tables are updated.

MME_EVENT_TRACKCHANGE

The MME delivers the event MME_EVENT_TRACKCHANGE when a track change occurs during playback.

Event data

This event returns the following data:

The requested and playing file IDs may be different when playback is requested during a ripping operation.

Database tables updated

The following tables are updated:

MME_EVENT_TRKSESSION

The MME delivers the event MME_EVENT_TRKSESSION when the track session in a control context has changed and a new track session ID (trksessionid) has been set for the control context, or when the number of tracks in a track session has changed.

Event data

The ID (trksessionid) of the new track session, in a uint64_t.

Database tables updated

The following table is updated:

MME_EVENT_TRKSESSIONVIEW_COMPLETE

The MME delivers the event MME_EVENT_TRKSESSIONVIEW_COMPLETE when it has finished updating the track session view in the trksessinview table.

Event data

The ID of the track session, in a uint64_t.

Database tables updated

The following table is updated:


Note: This event is delivered only when the MME has written to the tracksessionview table. For more information about configuring the MME track session view behavior, see Configuring playback behavior in the MME Configuration Guide.

MME_EVENT_TRKSESSIONVIEW_INVALID

The MME delivers the event MME_EVENT_TRKSESSIONVIEW_INVALID when a track session has changed, rendering the data in the trksessionview table invalid. This event indicates that MME will delete the data in the trksessionview table.

Event data

The ID of the track session whose information will be deleted from the trksessionview table, in a uint64_t.

Database tables updated

The following table is updated:

MME_EVENT_TRKSESSIONVIEW_UPDATE

The MME delivers the event MME_EVENT_TRKSESSIONVIEW_UPDATE when it has updated the data in the trksessionview table.

Event data

The ID of the track session whose data the MME has updated in the trksessionview table, in a uint64_t.

Database tables updated

The following table is updated:

MME_EVENT_VIDEO_STATUS

The MME delivers MME_EVENT_VIDEO_STATUS after it has changed the status of a video it is playing, including:

This information is in mm_event_data_t.video_status.

To find out the status of a video, call the function mme_video_get_status(). To change video attributes, call the relevant mme_video_set_*() function.

Event data

No data.

Database tables updated

No database tables are updated.

Playback error events

The MME playback error events are defined by the enumerated type mme_play_error_type_t:

typedef enum mme_play_error_type {
	...
    MME_PLAY_ERROR_*
    ...
} mme_play_error_type_t;

Playback errors are grouped by the type of command that can produce the error. This definition is in the enumerated type mme_command_type_t:

typedef enum mme_command_type {
    MME_COMMAND_TYPE_PLAY    = 1,
    MME_COMMAND_TYPE_BUTTON  = 2
} mme_command_type_t;

The playback error events are:

MME_PLAY_ERROR_BLOCKEDDOMAIN

The MME delivers the event MME_PLAY_ERROR_BLOCKEDDOMAIN when it blocks a user operation that is forbidden by a domain mask on the media source. For more information about these domains, see mme_dvd_get_status().

Event data

The type of user operation that was attempted, in mme_play_error_t.command_error.command, and:

Database tables updated

No database tables are updated.

MME_PLAY_ERROR_BLOCKEDUOP

The MME delivers the event MME_PLAY_ERROR_BLOCKEDUOP when it blocks a user operation. This sort of situation can occur when, for example, the user attempts to use a forbidden play or button command.

Event data

The type of user operation that was attempted, in mme_play_error_t.command_error.command, and:

Database tables updated

No database tables are updated.

MME_PLAY_ERROR_CORRUPT

The MME delivers the event MME_PLAY_ERROR_CORRUPT when the MME is unable to play a file for which it has the correct codec.

Event data

The file ID (fid) of the corrupt file, in mme_play_error_t.fid.

Database tables updated

The following table is updated:

MME_PLAY_ERROR_DEVICEREMOVED

The MME delivers the event MME_PLAY_ERROR_DEVICEREMOVED when the mediastore (or device and mediastore) from which it is playing is removed from the system. The MME will stop playback, deliver this error event, then deliver the event MME_EVENT_PLAY_ERROR.

Event data

The mediastore ID (msid) of the mediastore with the file or track that was being played when the mediastore was removed, in mme_play_error_t.msid.

Database tables updated

The following table is updated:

MME_PLAY_ERROR_INPUTUNDERRUN

The MME delivers the event MME_PLAY_ERROR_INPUTUNDERRUN when it encounters problems filling its input buffer and has an input underrun. An input underrun is usually caused by slow input media. The MME_PLAY_ERROR_INPUTUNDERRUN signals a warning: the input underrun results in an audible gap during playback, but playback will continue.

Event data

The file ID (fid) of the file that had the input underrun, in mme_play_error_t.fid.

Database tables updated

No database tables are updated.

MME_PLAY_ERROR_INVALIDFID

The MME delivers the event MME_PLAY_ERROR_INVALIDFID when it is requested to play an invalid file ID. This situation can occur if the requested fid is not found in the library table, or if it is not included in the currently active track session.

Event data

The invalid fid number, in mme_play_error_t.fid.

Database tables updated

No database tables are updated.

MME_PLAY_ERROR_MEDIABUSY

The MME delivers the event MME_PLAY_ERROR_MEDIABUSY when it has attempted to start playback of a file, but the mediastore is being used by another operation and is locked.

Event data

The file ID (fid) of the file that failed playback, in mme_play_error_t.fid.

Database tables updated

No database tables are updated.

MME_PLAY_ERROR_INVALIDSAVEDSTATE

The MME delivers the event MME_PLAY_ERROR_INVALIDSAVEDSTATE if it attempts but fails to resume playback on a mediastore. Delivery of this event indicates that the data saved for the track session is incorrect or corrupt.

Event data

The file ID of the track where the error occurred, in mme_play_error_t.fid.

Database table updated

No database tables are updated.

MME_PLAY_ERROR_NETWORK

The MME delivers the event MME_PLAY_ERROR_NETWORK when a network error had caused playback to fail.

Event data

The file ID (fid) of the file that failed playback, in mme_play_error_t.fid.

Database tables updated

No database tables are updated.

MME_PLAY_ERROR_NOEXIST

The MME delivers the event MME_PLAY_ERROR_NOEXIST when it has failed to play a file because the file does not exist, or because the file's specified content was not found. This situation can occur in situations such as the following:

Event data

The file ID (fid) of the file that failed playback, in mme_play_error_t.fid.

Database tables updated

No database tables are updated.

MME_PLAY_ERROR_NOOUTPUTDEVICES

The MME delivers the event MME_PLAY_ERROR_NOOUTPUTDEVICES when it starts playback of a file, but no output devices are attached to the control context with the playback.

Event data

The file ID (fid) of the file that failed playback, in mme_play_error_t.fid.

Database tables updated

No database tables are updated.

MME_PLAY_ERROR_NORIGHTS

The MME delivers the event MME_PLAY_ERROR_NORIGHTS when it encounters a DRM protected file which it is not licensed to decrypt and cannot play.

Event data

The file ID (fid) of the file that failed playback, in mme_play_error_t.fid.

Database tables updated

No database tables are updated.

MME_PLAY_ERROR_NOTSPECIFIED

The MME delivers the event MME_PLAY_ERROR_NOTSPECIFIED when playback fails for a reason not covered by the other playback error events, or when the MME is unable to determine the cause of the failure.

Event data

No event data is delivered.

Database tables updated

No database tables are updated.

MME_PLAY_ERROR_OUTPUTFAILEDATTACH

The MME delivers the event MME_PLAY_ERROR_OUTPUTFAILEDATTACH when it has failed to attach an output that is part of its current zone. The MME_PLAY_ERROR_OUTPUTFAILEDATTACH signals a warning: playback continues.

Event data

The file ID (fid) of the file that failed playback, in mme_play_error_t.fid.

Database tables updated

No database tables are updated.

MME_PLAY_ERROR_PARENTALCONTROL

The MME delivers the event MME_PLAY_ERROR_PARENTALCONTROL when it parental control settings have prevented it from playing a requested track or file.

Event data

The file ID (fid) of the file that failed playback, in mme_play_error_t.fid.

Database tables updated

No database tables are updated.

MME_PLAY_ERROR_READ

The MME delivers the event MME_PLAY_ERROR_READ when it is playing a track or file and it encounters a read error.

Event data

The file ID (fid) of the file that failed playback, in mme_play_error_t.fid.

Database tables updated

No database tables are updated.

MME_PLAY_ERROR_REGION

The MME delivers the event MME_PLAY_ERROR_REGION when it is unable to continue playback because the regional settings for a mediastore do not correspond to the regional settings for the device playing the mediastore.

Event data

The file ID (fid) of the file that failed playback, in mme_play_error_t.fid.

Database tables updated

No database tables are updated.

MME_PLAY_ERROR_OUTPUTUNDERRUN

The MME delivers the event MME_PLAY_ERROR_OUTPUTUNDERRUN when its output buffer is drained during playback and the MME has encountered an output underrun. An output underrun is usually caused by a slow system decode process, which is unable to keep up with audio output at normal speed (1 ×). The MME_PLAY_ERROR_OUTPUTUNDERRUN signals a warning: the output underrun results in an audible gap during playback, but playback will continue.

Event data

The file ID (fid) of the file that had the output underrun, in mme_play_error_t.fid.

Database tables updated

No database tables are updated.

MME_PLAY_ERROR_UNSUPPORTEDCODEC

The MME delivers the event MME_PLAY_ERROR_UNSUPPORTEDCODEC after it starts playback and determines that it does not have the codec it needs to decode the stream it is attempting to play.

Event data

The file ID (fid) of the file that failed playback, in mme_play_error_t.fid.

Database tables updated

The following table is updated: