Customize names of transcoded files

File name definition

A file name consists of variable strings and fixed strings. Variable strings are specific wildcard characters that are provided by VOD and can be dynamically replaced. Fixed strings cannot be dynamically replaced.

• Variable strings

  Variable strings, also known as wildcard characters, are placeholders for specific values. If you set a wildcard character, VOD retrieves the corresponding value and uses it to replace the wildcard character when it generates the transcoded file name. VOD supports the following wildcard characters:

  • Video ID: {MediaId}. This provides partial uniqueness because one video can have multiple transcoded outputs.

  • Transcoding job ID: {JobId}. This provides complete uniqueness and can uniquely identify a transcoded file.

  • Playback definition mark: {PlayDefinition}. This is not unique.

    Note

    The playback definition mark is the value of the Definition field that is returned by the GetPlayInfo operation. The value is a string in lowercase English.

• Fixed strings

  Fixed strings can represent specific business information. For example, `watermark` indicates a watermarked output, and `encrypt` indicates an encrypted output. In the default rules that are provided by VOD, an encrypted transcoding output includes the encrypt-stream keyword. You can also use custom rules to configure fixed strings for your specific business attributes.

  Example: In {MediaId}/{JobId}-watermark-sd and {MediaId}/encrypt-hd, the keywords `watermark` and `encrypt` indicate watermarking and encryption information.

Uniqueness of file names

To prevent transcoded output files from being overwritten, the configured name for each transcoded output file must be unique.

• Example of uniqueness:

  {MediaId}/{JobId}. `{MediaId}` provides partial uniqueness, and `{JobId}` provides global uniqueness. This ensures that the entire file name is unique.

• Non-unique name example:

  {MediaId}/test. `{MediaId}` provides only partial uniqueness, and `test` represents some business information. If you transcode a video into two MP4 files with different transcoding parameters, such as resolution and bitrate, the two MP4 output files for the same video will have the same name. This causes the files to be overwritten, and only one MP4 file will remain.

Default rules

VOD provides a set of default rules for generating output file names. The rules are as follows:

• Unencrypted output

  Format:

  {MediaId}/[Random string]-{PlayDefinition}

  Example:

  99f4f18c560c4f35459ef71tr/1b1196c767003c3dba0543055-40023f3f33e648df975f4dfc4c-sd

• Encrypted output

  Format:

  {MediaId}/[Random string]-{PlayDefinition}-encrypt-stream

  Example:

  99f4f18c560c4f35459ef71tr/1b1196c767003c3dba0543055-40023f3f33e648df975f4dfc4c-sd-encrypt-stream

  Note

  The encrypt-stream keyword indicates that the output file is an encrypted transcoding output. This applies only to HLS encryption (proprietary encryption and standard encryption).

Custom rules

In some business scenarios, you may want to reduce the overall playback response time. You can do this by directly constructing the playback address based on certain rules. For example, if the rule is {MediaId}/{PlayDefinition}, you can construct the file path using the `MediaId` and different definition marks without calling a playback API to retrieve the playlist. VOD lets you customize transcoding file name rules. VOD then generates file names based on your custom rules.

Rule limits

• Custom transcoding file names can contain only specific wildcard characters (variable strings), letters, digits, hyphens (-), and underscores (_). The total length of a custom rule cannot exceed 128 characters.

• Custom transcoding file names must start with the {MediaId} wildcard character. This ensures partial uniqueness and prevents transcoded files from different videos from conflicting with each other.

• Do not include a file extension in the custom file name because VOD automatically adds it. For example, if the naming rule is {MediaId}/{JobId}-watermark-{PlayDefinition} and the output format is mp4, VOD automatically adds the .mp4 extension when it generates the file name.

  Example: 99f4f18c560c4f35459ef71tr/1b1196c767003c3dba0543055-watermark-sd.mp4

• Make sure that your custom rules generate a unique name for each transcoded file to prevent files from being overwritten.

Configuration methods

You can customize transcoding file names only using the API. For more information, see AddTranscodeTemplateGroup. For details about the parameter, see the TranscodeFileRegular parameter in TranscodeTemplate.

Configuration example

public static JSONArray buildTranscodeTemplateList() {
        JSONObject transcodeTemplate = new JSONObject();
        // Customize the output file name for transcoding.
        transcodeTemplate.put("TranscodeFileRegular", "{MediaId}/{JobId}-watermark-{PlayDefinition}");
        // Template name.
        transcodeTemplate.put("TemplateName", "testtemplate");
        // Definition.
        transcodeTemplate.put("Definition", "LD");
        ......
        // Configure parameters such as video transcoding, audio transcoding, and output format.
        ......
        JSONArray transcodeTemplateList = new JSONArray();
        transcodeTemplateList.add(transcodeTemplate);
        return transcodeTemplateList;
    }

For more information about how to add a transcoding template group, see Transcoding templates.