mmr_input_attach()

Attach an input.

Synopsis:

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

Since:

BlackBerry 10.0.0

Arguments:

ctxt

A context handle

url

The URL of the new input

type

The input type.

Library:

libmmrndclient (For the qcc command, use the -l mrndclient option to link against this library)

Description:

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

The input type is one of:

  • track - This input type tells mm-renderer that the input URL refers to a track (that is, a media file or stream). For this input type, mm-renderer uses a simple interface with no playlist window, no track parameters or track metadata, and positions expressed as a single number.
  • playlist - This input type tells mm-renderer that the input URL refers to a playlist file. For this input type, mm-renderer uses a rich interface with a playlist window, track parameters and track metadata, and positions expressed as a pair of numbers.
  • autolist - This input type tells mm-renderer that the app wants the same rich interface that the playlist type provides. Currently, the input URL has to refer to a track (that is a media file or a stream) rather than an actual playlist file, but the interface behaves as if that track is the only entry in a playlist.

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 differently for each of the supported input types. Also, mmr_list_change() applies to "playlist" only.

Currently, valid input URLs for the "track" or "autolist" input types are:

  • An http: or https: URL of a file or an HTTP stream. 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.
    The mm-renderer service supports HLS version 3, with media segments encoded as follows:
    • Transport stream MPEG2-TS with H.264 Video, with either MP3 or AAC Audio (when the appropriate codecs are available on the platform)
    • Video only and audio only when embedded in the MPEG2-TS stream

    Note: To offer secure playback of video and audio content from HTTP Live Streaming and other HTTP sources, mm-renderer supports cookies, SSL, and authentication. The client must provide the necessary information (for example, username and password) using the OPT_* context parameters to use these security features.

  • A file: URL.
  • A full pathname starting with a "/" character.
  • 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 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
    • 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 (for example, 16)
      • bsize - the preferred read size, in bytes
    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 output or an error returned to the client.On the BlackBerry 10 OS, use audio: where possible rather than snd.
  • 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 (for example, 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.

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 (for example, spaces encoded as %20, and so on)

Note: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()).

Last modified: 2014-09-30



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus