mmr_input_attach()

Attach an input.

Synopsis:

#include <mm/renderer.h>
int mmr_input_attach( mmr_context_t *ctxt, 
                      const char *url, 
                      const char *type )

Arguments:

ctxt
A context handle.
url
The URL of the new input.
type
The input type. Possible values are "track", "playlist", and "autolist" (quotes are required), with the following meanings:
track
One track played in isolation from the rest of the media
playlist
A track sequence, with ordering information and track metadata contained in a playlist file
autolist
A single track formatted as a playlist; you can play the track continuously using the repeat input parameter

Library:

mmrndclient

Description:

Attach an input file, device, or playlist. If the context already has an input, detach it first.

The input type determines how mm-renderer responds to certain playback requests. For example, when seeking to track positions using mmr_seek(), you must specify the desired position one way for the "track" type, and another way for the "autolist" or "playlist" type. Also, mmr_list_change() is supported for "playlist" only.

Valid input URLs for the "track" or "autolist" input types are:

  • A URL starting with http:. HLS (HTTP Live Streaming) is supported just as any HTTP stream, with the following caveats:
    • For HLS realtime broadcast the seek operation is disabled. Therefore, if your application issues a seek command it will fail.
    • Pause (play speed of 0) is supported but the playback may jump forward when resumed because the current stream may have become unavailable.
    • For HLS Video on Demand, the seek operation places the play position at the start of the video chunk that is closest to the requested time. The pause operation works as expected.
  • A full pathname starting with a "/" character, with or without a file: or http: prefix
  • A file2b: URL containing the full path name of a dynamically growing file (a progressive download). Not all formats are supported. If parsing the file requires knowing the file size or reading more data than currently in the file, the input attachment operation may fail. If it does succeed, any attempt to play from beyond the end of file will cause the playback to underrun. Your application must pay attention to the buffering status and appropriately present the state to the user, depending on whether the download is happening at the time.
  • An snd: URL targeting an audio capture device (microphone) whose device file is located in /dev/snd. The URL can specify device configuration options in a comma-separated list, as follows: 
    snd:/dev/snd/pcmPreferredc?frate=44100&nchan=2
    Supported options include:
    • frate — the sampling rate, in Hertz
    • frag_ms — the fragment size, in milliseconds
    • nchan — the number of channels (1 for mono, 2 for stereo)
    • depth — the number of bits per sample (e.g., 16)
    • bsize — the preferred read size, in bytes
    Currently, this URL format works only with the "file" output type. The resulting behavior is identical to that for the audio: URL format except that the Audio Manager is bypassed, which means you can't provide hints such as audio type to control audio routing.
  • An audio: URL naming an audio capture device (microphone) whose name is defined by the AUDIO_DEVICE_NAMES set of string constants, which is listed in the Audio Manager Library reference. The URL can specify any of the options supported for snd: URLs, for example: 
    audio:voice?nchan=1&frate=44100&depth=16
    Currently, this URL format works only with the "file" output type. Client applications should use audio:default to specify automated routing for the audio stream unless there's a good reason to use one particular device. When a non-default device is named, the audio stream routing depends solely on that device. For instance, the removal of the device could result in no audio being outputted or an error returned to the client.

Valid input URLs for the "playlist" input type are:

  • A full pathname of an M3U playlist file, with or without a file: or http: prefix
  • An SQL URL in the form sql:database?query=query, where:
    • database is the full path to the database file
    • query must return a single column containing URLs in a form acceptable for the "track" input type
    • any special characters in the query must be URL-encoded (e.g., spaces encoded as %20, and so on)
Not all defined audio devices may work with the current application. It's the client's responsibility to determine if a particular device is supported before trying to use it. See the mmr_output_attach() example for a demo of how to check if an audio device is supported before configuring the audio routing.

Returns:

Zero on success, -1 on failure (use mmr_error_info()).

Classification:

QNX Neutrino

Safety:
Interrupt handler No
Signal handler No
Thread Yes

Example:

See the mmr_output_attach() example for a demo of how to select one audio device to use.