How to set up a transcoding template?

Definition of a Template

A template in AuroraCloud VOD is a predefined configuration that specifies how a video should be processed during transcoding. It includes parameters such as the output format (for example, MP4 or HLS), video and audio codecs, resolution, bitrate, watermark placement, and optional encryption settings. By creating a template, you can standardize and reuse transcoding settings across multiple videos. This not only ensures consistency in output quality and format but also simplifies future transcoding tasks by eliminating the need to manually configure each parameter every time

Summary

This guide will walk you through the process of creating a new template on the Visionular platform. Here are the detailed steps to create a template:

Step 1: Access the Template Page

Log in to your Visionular account.
Click on "Templates" in the left navigation bar.
On the "Templates" page, click the "Create a template" button.

Step 2: Fill in Basic Settings

Template Name: Enter a unique name for your template. The name must be unique and can contain letters, numbers, underscores, spaces, and other characters, up to 100 characters.
Template Description: Enter a description for your template, up to 100 characters.
Container Format: Select the container format from the dropdown menu, the default option is MP4.

Step 3: Configure Video Settings

Video Codec: Select the video codec format from the dropdown menu, the default option is H.264.
Quality: Select the encoding quality from the dropdown menu, ranging from [1, 10], the default value is 5. The higher the number, the better the video quality.
Frame Rate: Enter the frame rate, the default value is 0 fps, which means the original frame rate will be preserved.
Resolution Type: Select the resolution type from the dropdown menu, the default option is "Same as input".

Step 4: Configure Audio Settings

Audio Codec: The audio codec format is set to AAC, no other options are selectable.
Audio Sampling Rate: Select the audio sampling rate from the dropdown menu, the default option is 44.1kHz.
Audio Channels: Select the audio channels from the dropdown menu, the default option is Stereo (stereo).
Audio Bitrate: Enter the audio bitrate, the default value is 64kbps.

Step 5: Configure Watermark Settings (Optional)

Text Watermark

Enable Text Watermark Switch: Turn on this option to add a text watermark to the video.
Enter Text Content (Content): Enter the text you want to display on the video here.
Select Font Color (Font Color): Choose the color of the text from the dropdown menu to ensure it is clearly visible in the video.
Select Font Size (Font Size): Choose the size of the text from the dropdown menu, the default value is 16, which can be adjusted to fit the video content.
Select Font Type (Font Type): Choose the font style of the text from the dropdown menu to match the style or branding requirements of the video.
Select Position (Position): Choose the position of the text watermark on the video from the dropdown menu. Available positions typically include:
- Top Left: The top left corner of the video.
- Top Center: The top center of the video.
- Top Right: The top right corner of the video.
- Middle Left: The left center of the video.
- Center: The center of the video.
- Middle Right: The right center of the video.
- Bottom Left: The bottom left corner of the video.
- Bottom Center: The bottom center of the video.
- Bottom Right: The bottom right corner of the video.
Enter Time Interval (Time Interval): Set the duration for which the text watermark will be displayed in the video, ranging from [1, 60] seconds.

Image Watermark

Enable Image Watermark Switch: Turn on this option to add an image watermark to the video.
Enter Image URL (Image URL): Enter the URL of the image file here, ensuring the image file is accessible.
Select Position (Position): Choose the position of the image watermark on the video from the dropdown menu. Available positions are the same as for text watermarks, including:
- Top Left: The top left corner of the video.
- Top Center: The top center of the video.
- Top Right: The top right corner of the video.
- Middle Left: The left center of the video.
- Center: The center of the video.
- Middle Right: The right center of the video.
- Bottom Left: The bottom left corner of the video.
- Bottom Center: The bottom center of the video.
- Bottom Right: The bottom right corner of the video.
Enter Image Size (Size): Set the size of the image watermark, in the format "width px ~ height px". If not set, the image will maintain its original size.
Enter Time Interval (Time Interval): Set the duration for which the image watermark will be displayed in the video, ranging from [1, 60] seconds.

Step 6: Create the Template

After confirming all settings are correct, click the "Create" button to create the template.

Creating a Transcoding Task via API

import requests
from typing import Optional, Dict, Any, List

def create_hls_template(
    api_key: str,
    api_secret: str,
    template_name: str,
    adaptive_streams: List[Dict[str, Any]],
    format: str = "hls",
    acodec: str = "aac",
    seg_time: int = 10,
    seg_type: str = "fmp4",
    description: Optional[str] = None,
    **kwargs
) -> bool:
    """
    Create an HLS template with customizable parameters

    Args:
        api_key: Access Key ID for API authentication
        api_secret: Access Key Secret for API authentication
        template_name: Name of the template
        adaptive_streams: List of dictionaries containing stream configurations
        format: Output format (default: hls)
        acodec: Audio codec (default: aac)
        seg_time: HLS segment duration in seconds (default: 10)
        seg_type: Segment type (default: fmp4)
        description: Optional description for the template
        **kwargs: Additional optional parameters for the template

    Returns:
        bool: True if creation successful, False otherwise
    """
    url = "https://api.visionular.com/vodencoding/v1/add_template"
    headers = {
        "Content-Type": "application/json",
        "auth-type": "use-basic"
    }
    payload = {
        "template_name": template_name,
        "format": format,
        "acodec": acodec,
        "seg_time": seg_time,
        "seg_type": seg_type,
        "adaptive_streams": adaptive_streams,
        **kwargs
    }
    

    # Add description if provided
    if description:
        payload["description"] = description

    try:
        print("Sending request:", payload)
        response = requests.post(
            url,
            headers=headers,
            auth=(api_key, api_secret),
            json=payload,
            verify=True
        )
        
        # Print full response for debugging
        print("Response status:", response.status_code)
        print("Response headers:", response.headers)
        print("Response content:", response.text)
        
        response.raise_for_status()
        result = response.json()

        if result["code"] == 0:
            print(f"Template '{template_name}' created successfully!")
            return True
        else:
            print(f"Template creation failed: {result['msg']}")
            return False

    except requests.exceptions.HTTPError as e:
        print(f"HTTP Error: {e}")
        print(f"Response content: {e.response.text if e.response else 'No response'}")
        return False
    except Exception as e:
        print(f"Unexpected error: {e}")
        return False


# Example usage
if __name__ == "__main__":
    api_key = "your_api_key"
    api_secret = "your_api_secret"

    # Define the template configuration
    from datetime import datetime
    import random
    import string
    
    # Generate unique template name with timestamp and random suffix
    random_suffix = ''.join(random.choices(string.ascii_letters + string.digits, k=4))
    template_name = f"HLS_720p_1080p_{random_suffix}"
    adaptive_streams = [
        # 1080p stream
        {
            "vcodec": "h264",
            "resolution": "1080p",      # 1920x1080
            "quality": 8,               # High quality
            "video_bitrate": 2000000,   # 2 Mbps
            "audio_bitrate": 128000     # 128 kbps audio
        },
        # 720p stream
        {
            "vcodec": "h264",
            "resolution": "720p",       # 1280x720
            "quality": 7,               # Medium-high quality
            "video_bitrate": 1500000,   # 1.5 Mbps
            "audio_bitrate": 96000      # 96 kbps audio
        }
    ]
    description = "HLS template with 720p and 1080p streams, max bitrate 2Mbps"

    # Create the HLS template
    if create_hls_template(
        api_key=api_key,
        api_secret=api_secret,
        template_name=template_name,
        adaptive_streams=adaptive_streams,
        description=description
    ):
        print("HLS template created successfully!")
    else:
        print("Failed to create HLS template.")