Playing video with subtitles

When playing video through mm-renderer, you can add subtitles by defining an additional output and the right input parameters for the context. After playback has started, you can turn the subtitles off and on, and switch to different subtitles of the same format.

Note: Subtitles aren't supported in the shipped version of mm-renderer. If you need this capability, contact QNX Customer Support.

The example below shows how to attach a subpicture output type and set input parameters for reading subtitles, from a separate file or the video itself, and for configuring them during playback.

Defining the output for subtitles

In addition to attaching a video output, we must attach another output with a URL beginning with screen: because the subtitles will be rendered to a different window (but on the same display):

// Attach a subpicture output with a URL of type "screen:" because the 
// subtitles are sent to the same display as the video content
subpicture_output_id = mmr_output_attach( ctxt_videorec, 
                                          "screen:?initflags=invisible",
                                          "subpicture" );

if (subpicture_output_id == -1) {
    errorInfo = mmr_error_info(ctxt_videorec);
    /* Remaining error-handling code goes here */
    return EXIT_FAILURE;
}

In the output URL, we define the initflags=invisible option setting to make the subtitle window invisible upon creation. This lets us set the z-orders of the subtitle and video windows (through the Screen API) so the subtitles appear on top of the video when playback begins. For a demonstration of setting window properties with this API, as well as a list of options configurable in a screen: URL, see the “Defining the video and audio outputs” section.

Defining input parameters to support subtitles

Before attaching the video input, if we want to display subtitles read from an external file, we must set the subpicture_url input parameter. The parameter's value must be the URL of an accessible file containing subtitles. This URL can be in any format supported for the track input type. For the list of supported subtitle formats (and their file extensions), see the product release notes.

strm_dict_t* dict_input_params = strm_dict_new();

// Store the URL of the external subtitle file
if ( strm_dict_set( dict_input_params, 
                    "subpicture_url", 
                    "/fs/usb0/dontcry_spanish_subtitles.srt" ) < 0 ) {
    /* Error-handling code goes here */
}
else if ( mmr_input_parameters( ctxt_videorec,
                                dict_input_params ) < 0 ) {
    errorInfo = mmr_error_info(ctxt_videorec);
    /* Remaining error-handling code goes here */
    return EXIT_FAILURE;
}

If we want to instead read any subtitles embedded in the video file, we don't define subpicture_url (and hence, skip the above API call). When the input is attached, mm-renderer tries to start reading subtitles; where these subtitles are read from depends on whether subpicture_url is set.

Configuring subtitles

Subtitles can be configured after attaching the input and even after starting playback. (The “Defining the input and starting playback” section provides a code sample of these two actions.) By default, subtitles are visible, but you can hide them by setting subpicture_disable to 1 or yes; this could be done based on user action. To enable them again, set this parameter to 0 or no.

int processSubtitleDisable() 
{
    int retval = EXIT_SUCCESS;
    if ( strm_dict_set( dict_input_params, 
                        "subpicture_disable", 
                        "yes" ) < 0 ) {
        /* Error-handling code goes here */
        retval = EXIT_FAILURE;
    }
    else if ( mmr_input_parameters( ctxt_videorec,
                                    dict_input_params ) < 0 ) {
        /* Error-handling code goes here */
        retval = EXIT_FAILURE;
    }
    return retval;
}
...
int processSubtitleEnable() 
{
    int retval = EXIT_SUCCESS;
    if ( strm_dict_set( dict_input_params, 
                        "subpicture_disable", 
                        "no" ) < 0 ) {
        /* Error-handling code goes here */
        retval = EXIT_FAILURE;
    }
    else if ( mmr_input_parameters( ctxt_videorec,
                                    dict_input_params ) < 0 ) {
        /* Error-handling code goes here */
        retval = EXIT_FAILURE;
    }
    return retval;
}

When reading subtitles from the video file, you can change which track within the video container (i.e., input file) the subtitles are read from, by setting subpicture_index. When reading subtitles from a separate file, you can set subpicture_url again (at any time) to select a new file from which to read.

For full details on all of these parameters, see the “Defining parameters” section.