Edit

SAMI Media Source

  • Article

Synchronized Accessible Media Interchange (SAMI) is a format for adding captions to digital media. The captions are stored in a separate text file with the file name extension .smi or .sami.

In Media Foundation, SAMI caption files are supported through the SAMI media source. Use the Source Resolver to create an instance of the SAMI media source from a URL or byte stream. Media Foundation does not provide a component that displays SAMI captions. The application must interpret the caption data that it receives from the SAMI media source.

The following shows an example SAMI file.

<SAMI>
<HEAD>
    <STYLE TYPE="text/css">
    <!--
    P {
        font-family: Arial;
        background: #000000;
        text-align: center;
        }

#standard {Name: Standard; color: #FFFFFF; font-size: 14pt; } 
#hilite {Name: Youth; color: greenyellow; font-size: 18pt;}

    .ENUSCC { Name: English; lang: EN-US-CC; }
    .FRFRCC { Name: French; lang: fr-FR; } 

    -->
    </STYLE>
</HEAD>
<BODY>
    <SYNC Start="0">
        <P Class="ENUSCC">The <I>first</I> caption.</P>
        <P Class="FRFRCC">Un</P>
    </SYNC>
    <SYNC Start="3000">
        <P Class="ENUSCC">The <I>second</I> caption.</P>
        <P Class="FRFRCC">Deux</P>
    </SYNC>
    <SYNC Start="5000">
        <P Class="ENUSCC">The <I>third</I> caption.</P>
        <P Class="FRFRCC">Trois</P>
    </SYNC>
</BODY>
</SAMI>

The <STYLE> element contains style information. This example contains a base style for <P> elements, along with two named styles, "standard" and "hilite". The named styles are used to modify the base style. Captions are placed within <SYNC> elements. The start attribute gives the presentation time in milliseconds for that caption. The captions in this example are given in two languages, specified by their RFC-1766 language tags, "en-US" and "fr -FR". Within the captions, languages are identified by their class names; in this case, "ENUSCC" and "FRFRCC".

The SAMI media source creates one media stream for each language. By default, the first stream is selected and the remaining streams are deselected. The application can change the stream selection by calling IMFPresentationDescriptor::SelectStream and IMFPresentationDescriptor::DeselectStream. Each stream descriptor contains the following attributes.

Attribute Description
MF_SD_LANGUAGE Language tag, as given by the lang attribute.
MF_SD_SAMI_LANGUAGE Language name, as given by the Name attribute.

 

Each stream has the following media type:

Attribute Value
MF_MT_MAJOR_TYPE MFMediaType_SAMI
MF_MT_ALL_SAMPLES_INDEPENDENT TRUE

 

The SAMI source delivers each caption in a separate media sample. The sample time stamp and duration are derived from the <SYNC> element. The media buffer contained in the sample holds the caption as ASCII text. The caption style is embedded in the caption as an inline STYLE attribute. For example, given the previous SAMI file, and using the English-language stream with the default styles, the first media buffer would contain the following data. (The line breaks might differ from what is shown here.)

<P STYLE="
    font-family: Arial;
    background: #000000;
    text-align: center;
    Name: English; lang: EN-US-CC;  
    Name: Standard; color: #FFFFFF; 
    font-size: 14pt; ">The<I>first</I> caption.

SAMI Styles

To change the current style, use the IMFSAMIStyle interface. This interface is obtained by calling IMFGetService::GetService on the SAMI media source. (If you are using the SAMI media source with the Media Session, call GetService on the Media Session.) The service identifier is MF_SAMI_SERVICE.

The following example sets the current SAMI style, specified by index.

HRESULT SetSAMIStyleByIndex(IMFMediaSource *pSource, DWORD index)
{
    IMFSAMIStyle *pSami = NULL;

    DWORD cStyles;
    PROPVARIANT varStyles;

    HRESULT hr = MFGetService(pSource, MF_SAMI_SERVICE, IID_PPV_ARGS(&pSami));
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pSami->GetStyleCount(&cStyles);
    if (FAILED(hr))
    {
        goto done;
    }

    if (index >= cStyles)
    {
        hr = E_INVALIDARG;
        goto done;
    }

    hr = pSami->GetStyles(&varStyles);
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pSami->SetSelectedStyle(varStyles.calpwstr.pElems[index]);

done:
    PropVariantClear(&varStyles);
    SafeRelease(&pSami);
    return hr;
}

This example calls the following methods on the SAMI media source:

The list of style names is also stored on the presentation descriptor, in the MF_PD_SAMI_STYLELIST attribute.

Media Sources and Sinks

Supported Media Formats in Media Foundation