Playback Structures and Constants

Thsi chapter describes MediaFS structures and constants used for playback monitoring and control:

Playback structures

MediaFS uses the following data structures to report and control playback information of files in the MediaFS framework:

_media_date

struct _media_date {
    uint16_t year;
    uint8_t  second;
    uint8_t  minutes;
    uint8_t  hours;
    uint8_t  day;
    uint8_t  month;
    uint8_t  weekday;
    char     text[40];
}

The _media_date structure contains track date information. It is populated and returned by devctl() when this function successfully issues a DCMD_MEDIA_RELEASE_DATE message to a MediaFS file.

Member Type Description
year uint16_t The release date year (0000-9999).
second uint8_t The release date second (00-59).
minutes uint8_t The release date minute (00-59).
hours uint8_t The release date hour (00-59).
day uint8_t The release date day (01-31).
month uint8_t The release date month (01-12).
weekday uint8_t The release date day of the week (0-6), starting with 0 for Sunday and going to 6 for Saturday.
text char A free-form, NULL text field for date information for use with devices that cannot store date specifics. Maximum length is 39 characters. If this field is used, all other fields in this structure must be set to 0 (zero).

_media_play

struct _media_play {
    unsigned pos;
};

The _media_play structure is used in combination with the DCMD_MEDIA_PLAY_AT command to set the starting play position. It includes at least the members described in the table below.

Member Type Description
pos unsigned The offset from time zero, in seconds, at which to start playback.

_media_playback

struct _media_playback {
    uint32_t count;
    uint32_t index;
    uint8_t  state;
    uint8_t  flags;
    uint16_t metaseq;
    uint32_t length;
    uint32_t elapsed;
    uint32_t speed
};

The _media_playback structure has been deprecated and replaced by _media_playback_status.

_media_playback_status

struct _media_playback_status {
    uint32_t  flags;
    uint32_t  state;
    uint32_t  speed;
    uint32_t  trkidx_total;
    uint32_t  trkidx_current;
    uint32_t  trkpos_total;
    uint32_t  trkpos_current;
    uint32_t  chpidx_total;
    uint32_t  chpidx_current;
    uint32_t  chppos_total;
    uint32_t  chppos_start;
    uint32_t  metaseq;
    uint32_t  reserved[4];
};

The _media_playback_status structure contains information about the current playback state of the device. It is returned when a DCMD_MEDIA_PLAYBACK message is sent to the control file. Any change to any element in this structure must trigger a notification event on the MediaFS control file. The _media_playback_status structure includes at least the members described in the table below.

For more information about possible values for playback states and flags values, see Media playback constants below.

Member Type Description
flags uint32_t Flags to indicate the playback speed status as well as other information about a media file. See The flags and speed members and Media playback constants below.
state uint32_t The current playback state of the device. Must be one of PLAYBACK_STATE_STOP, PLAYBACK_STATE_PLAY or PLAYBACK_STATE_PAUSE. This value must be updated on a device playback state change. See Media playback constants below.
speed uint32_t The playback speed. This value is valid only if the PLAYBACK_FLAG_FASTFWD or the PLAYBACK_FLAG_FASTRWD flag is set. See The flags and speed members below.
trkidx_total uint32_t The total number of tracks in the playback list.
trkidx_current uint32_t The index reference for the currently playing track.
trkpos_total uint32_t The length of the currently playing track, in milliseconds. Set to 0 if the track length is not known.
trkpos_current uint32_t The current position in the currently playing track, in milliseconds.
chpidx_total uint32_t The total number of chapters in the current media item. Set to 0 (zero) if there are no chapters.
chpidx_current uint32_t The index reference for the currently playing chapter.
chppos_total uint32_t The length of the currently playing chapter, in milliseconds. Set to 0 (zero) if the chapter length is not known.
chppos_start uint32_t The offset, in milliseconds, from the start of the chapter from which to start playback of the chapter. Set to 0 (zero) if this offset is not known.
metaseq uint32_t A sequence number that changes if metadata values have changed during playback of the current track.
reserved [4] uint32_t Reserved for future use.

The flags and speed members

The value of the flags member can be a combination of:

The PLAYBACK_FLAG_FASTFWD and PLAYBACK_FLAG_FASTRWD flag values are exclusive. If you set one, you must not set the other.

If flags is non-zero and the media device supports an indication of the exact playback speed, then PLAYBACK_FLAG_SPEED_EXACT flag can be set.

The speed member is updated on a playback speed change: 0 means paused, and 1 (one) means normal playback speed. The value of speed is only valid if the PLAYBACK_FLAG_SPEED_EXACT flag is set. If the PLAYBACK_FLAG_SPEED_EXACT flag is not set in the flags member, speed should be set to 0 (zero).

You should combine the PLAYBACK_FLAG_* values to set the flags member.

See also Media playback constants below.

_media_settings

struct _media_settings {
    uint8_t value
};

The _media_setting structure is used in conjunction with the DCMD_MEDIA_GET_SHUFFLE, DCMD_MEDIA_SET_SHUFFLE, DCMD_MEDIA_GET_REPEAT and DCMD_MEDIA_SET_REPEAT device control messages. It contains the repeat or random mode setting for the device, and includes at least the members described in the table below.

Member Type Description
value uint8_t The repeat or random mode value for the device.

Separate messages must be issued for getting and setting random and repeat modes; that is, it is not possible to get or set both the random and the repeat mode with one devctl() call. See also Repeat and random mode setting constants below.

_media_speed

struct _media_speed {
    unsigned rate;
};

The _media_speed structure is used to set the current playback speed of the media device. The rate is a multiplication factor, where 1 (one) is normal playback speed. Valid values are 1, 2, 4, 8, 16 and 32.

This structure is used in conjunction with the DCMD_MEDIA_FASTFWD and DCMD_MEDIA_FASTRWD commands. It includes at least the members described in the table below.

Member Type Description
rate unsigned The playback speed multiplication factor; 1 (one) is normal speed.

_media_stream_info

struct _media_stream_info {
    unsigned char is_DRM;
    unsigned char seek_supported;
    unsigned char unused[2];
    uint32_t      reserved;
    uint64_t      stream_length;
};

The _media_stream_info structure is used to carry information that affects how a media stream can be played. It includes at least the members described in the table below:

Member Type Description
is_DRM char Indicate if the media stream is DRM (Digital Rights Management) protected. Set to either Y (protected) or N (not protected).
seek_supported char Indicate if the media stream supports seek capabilities. Set to either Y (supported) or N (not supported).
unused [2] char Reserved for future use.
reserved uint32_t Reserved for future use.
stream_length uint64_t The length of the media stream, in bytes. Set to MEDIA_STREAM_LENGTH_UNKNOWN if the media stream length is not known.

Playback constants

The tables below list the constants defined in dcmd_media.h for playback monitoring and control.

Media playback constants

The PLAYBACK_FLAG_* and PLAYBACK_STATE_* constants are defined in the structure _media_playback_status; they set or describe playback states.

Constant Value Description
PLAYBACK_FLAG_FASTFWD 0x01 Playback is in fast forward mode; the DCMD_MEDIA_FASTFWD control message has been applied, and playback speed is set to a number other than 1 (one).
PLAYBACK_FLAG_FASTRWD 0x02 Playback is in fast rewind mode; the DCMD_MEDIA_FASTRWD control message has been applied, and playback speed is set to a number other than 1 (one).
PLAYBACK_FLAG_SPEED_EXACT 0x04 The playback speed is the exact device speed; otherwise the playback speed is the value set with a DCMD_MEDIA_FAST*WD control message.
PLAYBACK_FLAG_EVENTS 0x08 Events are waiting to be retrieved from the event queue.
PLAYBACK_FLAG_ALBART 0x10 Album art is available to be read by a call with the DCMD_MEDIA_ALBART_READ control message.
PLAYBACK_FLAG_IS_VIDEO 0x20 Video is currently playing.
PLAYBACK_STATE_STOP 0 Playback is stopped.
PLAYBACK_STATE_PLAY 1 Playback is underway (not paused or stopped).
PLAYBACK_STATE_PAUSE 2 Playback is paused.

Repeat and random mode setting constants

The REPEAT_* and SHUFFLE_* constants set or describe playback repeat and random mode settings. The REPEAT_* values should be used with the DCMD_MEDIA_*_REPEAT messages, and the SHUFFLE_* should be used with the DCMD_MEDIA_*_SHUFFLE messages.

Constant Value Description
REPEAT_OFF 0 Repeat mode is off.
REPEAT_ONE_TRACK 1 Repeat the current track only.
REPEAT_ALL_TRACKS 2 Repeat all tracks.
REPEAT_FOLDER 3 Repeat all tracks in the folder.
REPEAT_SUBFOLDER 4 Repeat all tracks in the subfolder.
SHUFFLE_OFF 0 Random mode is off.
SHUFFLE_TRACKS 1 Play all tracks in pseudo-random order.
SHUFFLE_ALBUMS 2 Play all albums in pseudo-random order. The playback order of the tracks depends on whether SHUFFLE_TRACKS is set.
SHUFFLE_FOLDER 3 Play all tracks in the folder in pseudo-random order.
SHUFFLE_SUBFOLDER 4 Play all tracks in the subfolder in pseudo-random order.

Media stream constants

The MEDIA_STREAM_* constants set or describe media streams.

Constant Value Description
MEDIA_STREAM_LENGTH_UNKNOWN -1 The media stream length is not known.

Media type strings

The table below lists common media type strings used in the info.xml file's <media>/<type> element to describe the mediastore. These mediastore types are consistent with the mediastore types defined by the MME's MME_STORAGETYPE_* constants in order to map type to string.

Constant Value Description
MEDIA_TYPE_UNKNOWN “UNKNOWN” Unknown storage type
MEDIA_TYPE_AUDIOCD “AUDIOCD” Audio CD
MEDIA_TYPE_VCD “VCD” Video CD
MEDIA_TYPE_SVCD “SVCD” Super Video CD
MEDIA_TYPE_FS “FS” RAM disc
MEDIA_TYPE_DVDAUDIO “DVDAUDIO” Audio DVD
MEDIA_TYPE_DVDVIDEO “DVDVIDEO” Video DVD
MEDIA_TYPE_IPOD “IPOD” iPod device
MEDIA_TYPE_KODAKCD “KODAKCD” Kodak picture CD
MEDIA_TYPE_PICTURECD “PICTURECD” Other picture CD
MEDIA_TYPE_A2DP “A2DP” A2DP protocol for Bluetooth
MEDIA_TYPE_SMB “SMB” MEDIA_TYPE_FS
MEDIA_TYPE_FTP “FTP” Internet FTP connection
MEDIA_TYPE_HTTP “HTTP” Internet HTTP connection
MEDIA_TYPE_NAVIGATION “NAVIGATION” Navigation CD or DVD.
MEDIA_TYPE_PLAYSFORSURE “PFS” PlaysForSure and similar devices.
MEDIA_TYPE_UPNP “UPNP” Devices using UPnP protocol.

iPod structures

MediaFS uses the following data structures to manage iPod devices:

_media_ipod_daudio

struct _media_ipod_daudio {
    unsigned  rate;
    int       sndchk;
    int       voladj;
    unsigned  reserved;
};

The _media_ipod_daudio structure is used to carry information about an iPod's capabilities, and instructions to be applied to the iPod. It includes at least the following members:

Member Type Description
rate unsigned The sample rate, in Hertz, for the media on the device. Standard values are 32000, 44100 and 48000; some devices also support 8000, 11025, 12000, 16000, 22050 or 24000 Hertz.
sndchk int The device sound check value, as gain in decibels plus or minus. If the sound check capabilitiy is disabled on the device, this value must be set to 0.
voladj int The device volume adjustment, a gain in decibels plus or minus.
reserved unsigned Reserved for future use.