> ## Documentation Index
> Fetch the complete documentation index at: https://docs.videodb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Subtitle Styles Reference

> Complete API reference for video.add_subtitle(SubtitleStyle()) function. Configure typography, colors, positioning, text transformation, borders and shadows for custom subtitle styling.

`video.add_subtitle(SubtitleStyle())` function supports many parameters for styling your captions or subtitles according to your brand and guidelines.

This document provides an API Reference to the parameters of `SubtitleStyle` function.

<Card title="Subtitles Guide" icon="book-open" href="/pages/act/subtitles/subtitles-guide">
  Dive deep into subtitle styling with practical examples and visual outputs
</Card>

## Styling Categories

<CardGroup cols={2}>
  <Card title="Typography and Style" icon="type">
    Font families, sizes, spacing, bold, italic, underline, and strike-through options
  </Card>

  <Card title="Color and Effects" icon="palette">
    Primary colors, secondary colors, outline colors, and background styling
  </Card>

  <Card title="Positioning and Margins" icon="move">
    Alignment configuration and margin settings for subtitle positioning
  </Card>

  <Card title="Text Transformation" icon="rotate-3d">
    Scaling, rotation, and skewing effects for subtitle text
  </Card>

  <Card title="Borders and Shadow" icon="lightbulb">
    Border styles, outlines, and shadow depth effects
  </Card>
</CardGroup>

## Import

Import `SubtitleStyle` from VideoDB module

<CodeGroup>
  ```python Python theme={null}
  from videodb import SubtitleStyle, connect

  conn = connect()
  coll = conn.get_collection()
  video = coll.get_video("MY_VIDEO_ID")

  video.add_subtitle(
      SubtitleStyle(
          font_name=<>,
          font_size=<>,
          spacing=<>,
          ...
      )
  )
  ```

  ```javascript Node.js theme={null}
  import { connect } from 'videodb';

  const conn = connect();
  const coll = await conn.getCollection();
  const video = await coll.getVideo("MY_VIDEO_ID");

  await video.addSubtitle({
      fontName: "<>",
      fontSize: "<>",
      spacing: "<>",
      // ...
  });
  ```
</CodeGroup>

## SubtitleStyle

This function supports following parameters for styling 👇

### `font_name`

The name of the font to use for the subtitles.

* Default: `"Arial"`
* Type: `str`

Checkout List of Supported Fonts below

### `font_size`

The size of the subtitle text in points.

* Default: `18`
* Type: `float`

### `primary_colour`

The color of the main subtitle text in `&HBBGGRR` or `&HAABBGGRR` format. See the Color Format section below for details.

* Default: `"&H00FFFFFF"` (white)
* Type: `str`

### `secondary_colour`

The color used for secondary effects like karaoke.

* Default: `"&H000000FF"` (red)
* Type: `str`

See the Color Format section below for details.

### `outline_colour`

The color of the text outline.

* Default: `"&H00000000"` (black)
* Type: `str`

See the Color Format section below for details.

### `back_colour`

The background color of the subtitle box.

* Default: `"&H00000000"` (black)
* Type: `str`

See the Color Format section below for details.

### `bold`

Indicates if the subtitle text is bold.

* Default: `False`
* Type: `bool`

### `italic`

Indicates if the subtitle text is italicized.

* Default: `False`
* Type: `bool`

### `underline`

Indicates if the subtitle text is underlined.

* Default: `False`
* Type: `bool`

### `strike_out`

Indicates if the subtitle text has a strikethrough.

* Default: `False`
* Type: `bool`

### `scale_x`

The horizontal scale of the subtitle text in percentage.

* Default: `1.0` (100%, no scaling)
* Type: `float`

### `scale_y`

The vertical scale of the subtitle text in percentage.

* Default: `1.0` (100%, no scaling)
* Type: `float`

### `spacing`

Space between characters in pixels.

* Default: `0`
* Type: `float`

### `angle`

The rotation angle of the subtitle text in degrees.

* Default: `0` (no rotation)
* Type: `float`

### `border_style`

The style of the border around the text.

* Default: `SubtitleBorderStyle.outline`
* Type: `int` or `SubtitleBorderStyle`

**This field accepts following value.**

* `SubtitleBorderStyle.no_border` or `1`
* `SubtitleBorderStyle.opaque_box` or `3`
* `SubtitleBorderStyle.outline` or `4`

**Usage:**

<CodeGroup>
  ```python Python theme={null}
  from videodb import SubtitleStyle, SubtitleBorderStyle, connect

  conn = connect()
  coll = conn.get_collection()
  video = coll.get_video("MY_VIDEO_ID")

  video.add_subtitle(
      SubtitleStyle(
          border_style=SubtitleBorderStyle.outline
      )
  )
  ```

  ```javascript Node.js theme={null}
  import { connect, SubtitleBorderStyle } from 'videodb';

  const conn = connect();
  const coll = await conn.getCollection();
  const video = await coll.getVideo("MY_VIDEO_ID");

  await video.addSubtitle({
      borderStyle: SubtitleBorderStyle.outline
  });
  ```
</CodeGroup>

### `outline`

The width (px) of the outline around the text.

* Default: `1.0` (px)
* Type: `float`

### `shadow`

The depth of the shadow behind the text in pixels.

* Default: `0.0`
* Type: `float`

### `alignment`

The position of the subtitle text on the screen, typically an enumerated type following the SSA/ASS standard.

* Default: `SubtitleAlignment.bottom_center`
* Type: `SubtitleAlignment` or `int`

**This field accepts following value.**

* `SubtitleAlignment.bottom_left` or `1`
* `SubtitleAlignment.bottom_center` or `2`
* `SubtitleAlignment.bottom_right` or `3`
* `SubtitleAlignment.middle_left` or `8, 9`
* `SubtitleAlignment.middle_center` or `10`
* `SubtitleAlignment.middle_right` or `11`
* `SubtitleAlignment.top_left` or `4,5`
* `SubtitleAlignment.top_center` or `6`
* `SubtitleAlignment.top_right` or `7`

**Usage:**

<CodeGroup>
  ```python Python theme={null}
  from videodb import SubtitleStyle, SubtitleAlignment, connect

  conn = connect()
  coll = conn.get_collection()
  video = coll.get_video("MY_VIDEO_ID")

  video.add_subtitle(
      SubtitleStyle(
          alignment=SubtitleAlignment.middle_center
      )
  )
  ```

  ```javascript Node.js theme={null}
  import { connect, SubtitleAlignment } from 'videodb';

  const conn = connect();
  const coll = await conn.getCollection();
  const video = await coll.getVideo("MY_VIDEO_ID");

  await video.addSubtitle({
      alignment: SubtitleAlignment.middleCenter
  });
  ```
</CodeGroup>

### `margin_l`

The left margin in pixels.

* Default: `10`
* Type: `int`

### `margin_r`

The right margin in pixels.

* Default: `10`
* Type: `int`

### `margin_v`

The vertical margin (both top and bottom) in pixels.

* Default: `10`
* Type: `int`

## Color Format

`SubtitleStyle` accepts colors in the `&HBBGGRR` hexadecimal format, where the sequence represents the blue, green, and red components.

`&H` prefix is required in this color format.

And when transparency is needed, an alpha value is placed at the beginning, yielding `&HAABBGGRR`.

## Supported Fonts

Currently VideoDB supports following Fonts:

* Sans
* Inter
* Roboto
* Open Sans
* Lato
* Montserrat
* Oswald
* Raleway
* Poppins
* Ubuntu
* Clear Sans
* Arial
* Times New Roman
* Courier New
* Georgia
* Verdana

Checkout the [Subtitles Guide](/pages/act/subtitles/subtitles-guide) to dive deep into the outputs of these parameters.