Using the Transcode API
This topic described how to use the transcode API to encode a media file.
- Overview
- Creating a Media Source
- Creating a Transcode Profile
- Creating a Transcode Topology
- Running the Encoding Session
- Related topics
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.
- Create a media source to read the source file.
- Create a transcode profile. Add attributes that describe the audio stream, video stream, and file container.
- Use the transcode profile to create an encoding topology. (For more information about topologies, see About Topologies.)
- Set the topology on the Media Session.
- 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 Attribute | Description |
|---|---|
| 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 Parameter | Description |
|---|---|
| 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 Attribute | Description |
|---|---|
| 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 Parameter | Description |
|---|---|
| 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.
| Attribute | Description |
|---|---|
| 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.
- Call MFCreateMediaSession to create the Media Session.
- Call IMFMediaSession::SetTopology to set the topology on the Media Session.
- Call IMFMediaSession::Start to start the encoding session.
- Wait for the MESessionEnded event.
- Call IMFMediaSession::Close to close the Media Session.
- Wait for the MESessionClosed event.
- Call IMFMediaSource::Shutdown.
- Call IMFMediaSession::Shutdown.
Most of the time spent encoding occurs between steps 3 and 4.
Related topics