Using the Transcode API

This topic described how to use the transcode API to encode a media file.

Overview

Before using the transcode API, the application must have the following pieces of information:

  • The path or URL to an existing media file that will be re-encoded.
  • The name of the output file.
  • The container type for the output file, such as MP4 or Advanced Streaming Format (ASF).
  • The encoding format. This information includes the media types that describe the encoded audio and video streams.

To use the transcode API, an application performs the following steps.

  1. Create a media source to read the source file.
  2. Create a transcode profile. Add attributes that describe the audio stream, video stream, and file container.
  3. Use the transcode profile to create an encoding topology. (For more information about topologies, see About Topologies.)
  4. Set the topology on the Media Session.
  5. Start the Media Session and wait for the MESessionEnded event.

The remainder of this topic describes these steps in more detail.

Creating a Media Source

A media source is an object that reads and parses the source file. To create a media source, use the Source Resolver. You can find example code in the topic Using the Source Resolver.

Creating a Transcode Profile

A transcode profile describes the format and settings that are used to encode the output file. The transcode profile contains three sets of attributes:

  • Audio attributes: Describe the target audio format and audio encoder settings.
  • Video attributes: Describe the target video format and video encoder settings.
  • Container attributes: Define the type of file container, as well as some global encoding settings.

To create a transcode profile, call the MFCreateTranscodeProfile function. This function returns a pointer to the IMFTranscodeProfile interface. The initial profile object is empty; it contains no attributes. The next step is to add the attributes that define the profile.

Audio Attributes

To add attributes for the audio stream, call IMFTranscodeProfile::SetAudioAttributes. These attributes specify how the audio stream is encoded. If the output file will not contain an audio stream, omit these attributes.

Audio attributes fall into two categories:

  • Attributes that specify the format of the encoded stream
  • Attributes that specify other encoding parameters.

Format attributes are simply media-type attributes, as described in the section Audio Media Types. The exact set of format attributes depends on the encoder. (See Supported Media Formats in Media Foundation.) Here is a list of typical audio format attributes:

Format AttributeDescription
MF_MT_SUBTYPE The subtype. See Audio Subtype GUIDs.
MF_MT_AUDIO_NUM_CHANNELS The number of audio channels.
MF_MT_AUDIO_SAMPLES_PER_SECOND The number of audio samples per second.
MF_MT_AUDIO_BLOCK_ALIGNMENT The block alignment.
MF_MT_AUDIO_AVG_BYTES_PER_SECOND The average number of bytes per second (the encoded bit rate).

 

The following encoding parameters are defined.

Encoding ParameterDescription
MF_TRANSCODE_DONOT_INSERT_ENCODER Prevents the transcode API from inserting an encoder for the audio stream.
MF_TRANSCODE_ENCODINGPROFILE Specifies the device conformance template. (Applies only to ASF files.)
MF_TRANSCODE_QUALITYVSSPEED Specifies the trade-off between encoding quality and speed.

 

You must set the format attributes. The encoding parameters are optional.

One way to find a format that is compatible with the encoder is to call the MFTranscodeGetAudioOutputAvailableTypes function. The desired encoder is specified by subtype. The function returns a collection of media types for that encoder. You can select a type from the list and copy the attributes to the profile. For example code that uses this approach, see Tutorial: Encoding a WMA File.

Video Attributes

To add attributes for the video stream, call IMFTranscodeProfile::SetVideoAttributes. These attributes specify how the video stream is encoded. If the output file will not contain a video stream, omit these attributes.

As with audio attributes, the video attributes fall into two categories:

  • Attributes that specify the format of the encoded stream
  • Attributes that specify other encoding parameters.

Format attributes are media-type attributes, as described in the section Video Media Types. Here is a list of typical video format attributes:

Format AttributeDescription
MF_MT_SUBTYPE The subtype. See Video Subtype GUIDs.
MF_MT_FRAME_RATE The frame rate.
MF_MT_FRAME_SIZE The frame size.
MF_MT_AVG_BITRATE The average bit rate.
MF_MT_PIXEL_ASPECT_RATIO The pixel aspect ratio.

 

The following encoding parameters are defined.

Encoding ParameterDescription
MF_TRANSCODE_DONOT_INSERT_ENCODER Prevents the transcode API from inserting an encoder for the video stream.
MF_TRANSCODE_ENCODINGPROFILE Specifies the device conformance template. (Applies only to ASF files.)
MF_TRANSCODE_QUALITYVSSPEED Specifies the trade-off between encoding quality and speed.

 

You must set the format attributes. The encoding parameters are optional.

Container Attributes

Container attributes define file-level characteristics of the output file. To set container attributes, call IMFTranscodeProfile::SetContainerAttributes. The following attributes are defined.

AttributeDescription
MF_TRANSCODE_ADJUST_PROFILE Defines the stream settings to use for the transcode topology. You can set the flags to use the input source settings or use custom stream attributes.
MF_TRANSCODE_CONTAINERTYPE Specifies the file format of the output file, such as MP4 or ASF. Based on this value, the appropriate media sink is added to the topology.
MF_TRANSCODE_SKIP_METADATA_TRANSFER Specifies whether metadata from the source is copied to the output file.
MF_TRANSCODE_TOPOLOGYMODE Specifies whether hardware-based codecs may be used during transcoding.
MFT_FIELDOFUSE_UNLOCK_Attribute Unlocks a codec that has field-of-use restrictions. For more information, see Field of Use Restrictions.

 

The MF_TRANSCODE_CONTAINERTYPE attribute is required. The other container attributes are optional.

Creating a Transcode Topology

The transcode topology is a partial topology that contains the media source, the appropriate codecs, and the media sink. To create the transcode topology, call to the MFCreateTranscodeTopology function. This function takes the following parameters as input:

  • A pointer to the IMFMediaSource interface of the media source.
  • The name of the output file.
  • A pointer to the IMFTranscodeProfile interface of the transcode profile.

The function returns a pointer to the IMFTopology interface.

Running the Encoding Session

After you create the topology, you are ready to encode the file. You can discard the profile at this point.

  1. Call MFCreateMediaSession to create the Media Session.
  2. Call IMFMediaSession::SetTopology to set the topology on the Media Session.
  3. Call IMFMediaSession::Start to start the encoding session.
  4. Wait for the MESessionEnded event.
  5. Call IMFMediaSession::Close to close the Media Session.
  6. Wait for the MESessionClosed event.
  7. Call IMFMediaSource::Shutdown.
  8. Call IMFMediaSession::Shutdown.

Most of the time spent encoding occurs between steps 3 and 4.

Related topics

Transcode API
About the Media Session

 

 

Show: