schema_version: 7.0
type: filter
identifier: qtext
title: QText
version: 5
copyright: Meltytech, LLC
license: LGPLv2.1
language: en
tags:
  - Video
description: Overlay text onto the video

parameters:
  - identifier: argument
    title: Text
    type: string
    description: |
      The text to overlay.
    argument: yes
    required: yes
    default: text
    widget: text

  - identifier: geometry
    title: Geometry
    type: rect
    description: A set of X/Y coordinates by which to adjust the text.
    default: 0%/0%:100%x100%:100
    mutable: yes
    animation: yes

  - identifier: family
    title: Font family
    type: string
    description: >
      The typeface of the font.
    default: Sans
    mutable: yes
    widget: combo

  - identifier: size
    title: Font size
    type: integer
    description: >
      The size in pixels of the font. 
    default: 48
    mutable: yes
    widget: spinner
    unit: pixels

  - identifier: style
    title: Font style
    type: string
    description: >
      The style of the font.
    values:
      - normal
      - italic
    default: normal
    mutable: yes
    widget: combo

  - identifier: weight
    title: Font weight
    type: integer
    description: The weight of the font.
    minimum: 100
    maximum: 1000
    default: 400
    mutable: yes
    widget: spinner

  - identifier: fgcolour
    title: Foreground color
    type: color
    description: >
      A color value is a hexadecimal representation of RGB plus alpha channel 
      as 0xrrggbbaa. Colors can also be the words: white, black, red, green,
      or blue. You can also use a HTML-style color values #rrggbb or #aarrggbb.
    default: 0x000000ff
    mutable: yes
    widget: color
    animation: yes

  - identifier: bgcolour
    title: Background color
    type: color
    description: >
      A color value is a hexadecimal representation of RGB plus alpha channel 
      as 0xrrggbbaa. Colors can also be the words: white, black, red, green,
      or blue. You can also use a HTML-style color values #rrggbb or #aarrggbb.
    default: 0x00000020
    mutable: yes
    widget: color
    animation: yes

  - identifier: olcolour
    title: Outline color
    type: color
    description: >
      A color value is a hexadecimal representation of RGB plus alpha channel 
      as 0xrrggbbaa. Colors can also be the words: white, black, red, green,
      or blue. You can also use a HTML-style color values #rrggbb or #aarrggbb.
    mutable: yes
    widget: color
    animation: yes

  - identifier: outline
    title: Outline Width
    type: string
    description: >
      The width of the outline in pixels.
    default: 0
    minimum: 0
    maximum: 3
    mutable: yes
    widget: spinner
    unit: pixels

  - identifier: pad
    title: Padding
    type: integer
    description: >
      The number of pixels to pad the background rectangle beyond edges of text.
    default: 0
    mutable: yes
    widget: spinner
    unit: pixels

  - identifier: halign
    title: Horizontal alignment
    description: >
      Set the horizontal alignment within the geometry rectangle.
    type: string
    default: left
    values:
      - l
      - left
      - c
      - center
      - centre
      - r
      - right
    mutable: yes
    widget: combo

  - identifier: valign
    title: Vertical alignment
    description: >
      Set the vertical alignment within the geometry rectangle.
    type: string
    default: top
    values:
      - t
      - top
      - m
      - middle
      - b
      - bottom
    mutable: yes
    widget: combo

  - identifier: html
    title: HTML String
    type: string
    description: >
      Render rich text from a string containing a subset of HTML 4.
      The only other properties that can be used with this are geometry and
      bgcolour. The geometry width and height defines the page or block size
      while its X and Y coordinates determine its position.
      This property has a higher priority than argument; argument is ignored if
      this property is set.
    mutable: yes

  - identifier: resource
    title: HTML File
    type: string
    description: >
      Render rich text from a file containing a subset of HTML 4.
      The only other properties that can be used with this are geometry and
      bgcolour. The geometry width and height defines the page or block size
      while its X and Y coordinates determine its position.
      This property has a higher priority than both argument and html; argument
      and html are ignored if this property is set.
    mutable: yes

  - identifier: _hide
    title: Hide
    type: boolean
    description: >
      Setting this property will not be serialized (unlike "disable"). When set
      true (1), the filter does not render. This allows an authoring tool to
      provide its own rendering while editing and then let the filter render
      outside the tool UI.
    mutable: yes
    default: 0

  - identifier: overflow-y
    title: Vertical Overflow
    type: boolean
    description: >
      This option applies only when using html or resource properties. It
      controls whether the text will be cropped to the geometry property or
      allowed to overflow. When not set, it is automatic based on whether the
      geometry height is greater than or equal to the profile height. The
      default is unset/automatic.
    mutable: yes

  - identifier: pixel_ratio
    title: Pixel Ratio
    type: float
    description: >
      This option applies only when using html or resource properties. It adds
      a scaling factor to the rendering. This can be used to help to make MLT's
      output match a user interface.
      NOTE: this property is only used on Windows because it is the only platform
      found thus far that has different rendering behavior relative to device
      pixel ratio.
    minimum: 1.0
    default: 1.0
    mutable: yes

  - identifier: opacity
    title: Opacity
    type: float
    description: Opacity of all elements - text, outline, and background
    default: 1.0
    minimum: 0
    maximum: 1.0
    mutable: yes
    widget: slider
    
  - identifier: typewriter
    title: Typewriter Effect
    type: integer
    description: >
      Enable typewriter effect where text appears progressively over time.
    default: 0
    minimum: 0
    maximum: 1
    mutable: yes
    widget: checkbox
    
  - identifier: typewriter.step_length
    title: Typewriter Step Length
    type: integer
    description: >
      Number of frames between each character, word, or line appearance.
    default: 25
    minimum: 1
    mutable: yes
    widget: spinner
    
  - identifier: typewriter.step_sigma
    title: Typewriter Step Variation
    type: integer
    description: >
      Random variation in timing (standard deviation in frames).
    default: 0
    minimum: 0
    mutable: yes
    widget: spinner
    
  - identifier: typewriter.random_seed
    title: Typewriter Random Seed
    type: integer
    description: >
      Seed value for random number generation in timing variations.
    default: 0
    minimum: 0
    mutable: yes
    widget: spinner
    
  - identifier: typewriter.macro_type
    title: Typewriter Animation Mode
    type: integer
    description: >
      Granularity of typewriter animation.
    values:
      - 1 # Character by character
      - 2 # Word by word  
      - 3 # Line by line
    default: 1
    mutable: yes
    widget: combo
    
  - identifier: typewriter.cursor
    title: Typewriter Cursor
    type: integer
    description: >
      Show blinking cursor during typewriter animation.
      0 = no cursor, 1 = cursor while typing, 2 = cursor always visible.
    default: 1
    minimum: 0
    maximum: 2
    mutable: yes
    widget: combo
    
  - identifier: typewriter.cursor_blink_rate
    title: Cursor Blink Rate
    type: integer
    description: >
      Number of frames for cursor blink cycle (on + off).
    default: 25
    minimum: 0
    mutable: yes
    widget: spinner
    unit: frames
    
  - identifier: typewriter.cursor_char
    title: Cursor Character
    type: string
    description: >
      Character to use for the blinking cursor.
    default: "|"
    mutable: yes
    widget: text
