Skip to main content

🔧 Captions Configuration

Optional configurations

Please note all options listed here are optional. Unless needed, you do not need to provide any of the below options.

In this section, we delve into the advanced features and customization options available in the ZapCap API. The following guide will help you leverage the full potential of ZapCap, allowing for highly tailored and specific subtitle generation to meet your unique requirements.

Customizing the rendering task with renderOptions​

When creating a video task, the renderOptions property within the CreateVideoTaskRequestDto allows you to control various aspects of subtitle appearance and behavior. Below, we provide detailed information on how to customize these options.

Render Options Overview​

renderOptions:
  subsOptions:
    emoji: boolean
    emojiAnimation: boolean
    emphasizeKeywords: boolean
    animation: boolean
    punctuation: boolean
    displayWords: number
  styleOptions:
    top: number
    fontUppercase: boolean
    fontSize: number
    fontWeight: number
    fontColor: string
    fontShadow: string
    stroke: string
    strokeColor: string
  highlightOptions:
    randomColourOne: string
    randomColourTwo: string
    randomColourThree: string
subsOptions​
  • emoji: boolean - Enables or disables emojis in the subtitles.
  • emojiAnimation: boolean - Enables or disables animation for emojis in the subtitles.
  • emphasizeKeywords: boolean - Highlights important words in the subtitles. Highlighting is styled according to the selected template.
  • animation: boolean - Toggles animation for the subtitles. For example, some themes may have moving subtitles to add a dynamic feel to the video.
  • punctuation: boolean - Determines whether punctuation should be added to the subtitles.
  • displayWords: number - Number of words to display. Note, this is a guidance, actual number of words displayed may vary slightly depending on the template.
styleOptions​
  • top: number - The Y position of the subtitles as a percentage of the video's height. Higher values place the subtitles lower on the video.
  • fontUppercase: boolean - Converts subtitles text to uppercase.
  • fontSize: number - Specifies the font size of the subtitles.
  • fontWeight: number - Specifies the font weight of the subtitles. Refer to the numerical values for font-weight in css.
  • fontColor: string - Sets the base color of the subtitles using a hex color code.
  • fontShadow: string - Sets the shadow size of the subtitles. Valid values are 'none', 's', 'm', 'l' (small, medium, large).
  • stroke: string - Sets the stroke size of the subtitles. Valid values are 'none', 's', 'm', 'l' (small, medium, large).
  • strokeColor: string - Sets the stroke color of the subtitles using a hex color code. (e.g. #000000)
highlightOptions​
  • randomColourOne: string - First random color option for highlighted keywords.
  • randomColourTwo: string - Second random color option for highlighted keywords.
  • randomColourThree: string - Third random color option for highlighted keywords.

Example: Creating a Video Task with Custom Render Options​

Below is an example request to create a video task with customized render options.

POST /videos/{videoId}/task
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
    "templateId": "a51c5222-47a7-4c37-b052-7b9853d66bf6",
    "autoApprove": false,
    "language": "en",
    "renderOptions": {
        "subsOptions": {
            "emoji": true,
            "emojiAnimation": true,
            "emphasizeKeywords": true,
            "animation": true,
            "punctuation": false,
            "displayWords": 6
        },
        "styleOptions": {
            "top": 40,
            "fontUppercase": true,
            "fontSize": 46,
            "fontWeight": 900,
            "fontColor": "#ffffff",
            "fontShadow": "l",
            "stroke": "s",
            "strokeColor": "#000000"
        },
        "highlightOptions": {
            "randomColourOne": "#2bf82a",
            "randomColourTwo": "#fdfa14",
            "randomColourThree": "#f01916"
        }
    }
}

This request demonstrates how to fully customize your subtitles to align with your brand and video content requirements. By adjusting these options, you can create a unique and engaging viewer experience or allow your users to customize their subtitles to their liking.

Customizing the transcription task with transcribeSettings​

In addition to rendering options, the ZapCap API allows you to customize the transcription process using the transcribeSettings property when creating a video task. This currently includes configuring b-roll options to enhance your video content.

Transcribe Settings Overview​

templateId: "a51c5222-47a7-4c37-b052-7b9853d66bf6",
transcribeSettings:
  broll:
    #Note: This is mutually exclusive with customBrolls
    brollPercent: 50
    #Note: This is mutually exclusive with brollPercent
    customBrolls: [
      {
        startTime: 10.5,
        endTime: 20.5,
        url: "https://example.com/broll.mp4"
      },
      {
        startTime: 30.1,
        endTime: 40.6,
        url: "https://example.com/another-broll.mp4"
      }
    ]
broll​
  • brollPercent: number - Specifies the percentage of b-roll footage to include in the video. Acceptable values range from 0 to 100. The default value is 50.
  • customBrolls: array - Allows you to specify your own b-roll clips with precise timing control. This is mutually exclusive with brollPercent.
customBrolls array items​

Each item in the customBrolls array must contain the following properties:

  • startTime: number - The start time in seconds when the b-roll should appear in the main video.
  • endTime: number - The end time in seconds when the b-roll should stop appearing in the main video.
  • url: string - The URL of the b-roll video. This must be a publicly accessible URL.
Important Notes for Custom B-rolls:​
  • Overlapping b-rolls are not allowed. The end time of one b-roll must be less than or equal to the start time of the next b-roll.
  • If a b-roll's time range exceeds the main video's duration, the b-roll will be truncated to match the video's duration.
  • If a b-roll's time range exceeds the b-roll video's actual duration, the b-roll will be rendered in full and its last frame will be repeated as needed to fill the specified time range.

Example: Creating a Video Task with Custom B-rolls​

POST /videos/{videoId}/task
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
    "templateId": "a51c5222-47a7-4c37-b052-7b9853d66bf6",
    "autoApprove": true,
    "language": "en",
    "transcribeSettings": {
        "broll": {
            "customBrolls": [
                {
                    "startTime": 5,
                    "endTime": 15,
                    "url": "https://example.com/intro-broll.mp4"
                },
                {
                    "startTime": 25,
                    "endTime": 35,
                    "url": "https://example.com/product-demo.mp4"
                }
            ]
        }
    }
}

This example demonstrates how to add custom b-rolls at specific points in your video, giving you precise control over when and what supplementary footage appears.

Customizing auto cutting with autoCutSettings​

The ZapCap API offers the ability to automatically remove silences from your videos using the autoCutSettings property when creating a video task. This feature helps create tighter, more engaging content by eliminating unwanted pauses.

Auto Cut Settings Overview​

templateId: "a51c5222-47a7-4c37-b052-7b9853d66bf6",
autoCutSettings:
  silenceRemoval: 0.3
autoCutSettings​
  • silenceRemoval: number - Controls how aggressively silences are removed from the video. Values range from 0 to 1. The lower the value, the less gap will be allowed between words, resulting in faster cuts and shorter videos. For example, a value of 0.4 would create tighter cuts compared to a value of 0.7.

Example: Creating a Video Task with Auto Cut Settings​

POST /videos/{videoId}/task
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
    "templateId": "a51c5222-47a7-4c37-b052-7b9853d66bf6",
    "autoApprove": true,
    "language": "en",
    "autoCutSettings": {
        "silenceRemoval": 0.4,
    }
}