schema_version: 7.0
type: filter
identifier: audiospectrum
title: Audio Spectrum Filter
version: 1
copyright: Meltytech, LLC
license: LGPLv2.1
language: en
tags:
  - Video
description: >
  An audio visualization filter that draws an audio spectrum on the image.

parameters:
  - identifier: type
    title: Graph type
    description: The type of graph to display the spectrum.
    type: string
    default: line
    values:
      - line
      - bar
    readonly: no
    mutable: yes
    widget: combo
    
  - identifier: bgcolor
    title: Background Color
    type: color
    description: |
      The background color to be applied to the entire frame. The default color 
      is transparent.
      
      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.
    readonly: no
    mutable: yes
    widget: color
    
  - identifier: color.*
    title: Foreground color
    type: color
    description: |
      The color of the waveform.
      
      Multiple colors can be specified with incrementing suffixes to cause the
      waveform to be drawn in a gradient. color.1 is the top of the waveform.
      Subsequent colors will produce a gradient toward the bottom.
      
      By default, the filter has one color defined:
      
          color.1=0xffffffff"
          
      This results in a white waveform.
      
      To create a gradient, define more colors:
      
          color.2=green color.3=0x77777777
      
      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.
    readonly: no
    mutable: yes
    widget: color

  - identifier: thickness
    title: Line Thickness
    type: integer
    description: >
      The thickness of the line used to draw the waveform for line graph.
      The thickness of the bar for bar graph.
    readonly: no
    default: 0
    minimum: 0
    maximum: 20
    mutable: yes
    widget: spinner
    unit: pixels
    
  - identifier: angle
    title: Angle
    type: float
    description: >
      The rotation angle to be applied to the waveform.
    readonly: no
    default: 0
    minimum: 0
    maximum: 360
    mutable: yes
    widget: spinner

  - identifier: rect
    title: Rectangle
    description: >
      Defines the rectangle that the waveform(s) should be drawn in.
      
      Format is: "X Y W H".
      
      X, Y, W, H are assumed to be pixel units unless they have the suffix '%'.
    type: rect
    default: "0 0 100% 100%"
    readonly: no
    mutable: yes
    animation: yes

  - identifier: fill
    title: Fill
    description: >
      Whether the area under the waveform should be filled in.
      Only applies to line graph type.
    type: boolean
    default: 0
    readonly: no
    mutable: yes
    widget: checkbox
    
  - identifier: mirror
    title: Mirror
    description: >
      Mirror the spectrum about the center of the rectangle.
    type: boolean
    default: 0
    readonly: no
    mutable: yes
    widget: checkbox
    
  - identifier: reverse
    title: Reverse
    description: >
      Draw the points starting with the highest frequency first.
    type: boolean
    default: 0
    readonly: no
    mutable: yes
    widget: checkbox
    
  - identifier: tension
    title: Line Tension
    description: >
      Affects the amount of curve in the line interpolating between points.
      0.0 = a straight line between points.
      1.0 = very curved lines between points.
      values < 0 and > 1 will cause loops in the lines.
      Only applies to line graph type.
    type: float
    default: 0.4
    readonly: no
    mutable: yes
    
  - identifier: gorient
    title: Gradient Orientation
    description: Direction of the color gradient.
    type: string
    default: vertical
    values:
      - vertical
      - horizontal
    readonly: no
    mutable: yes
    widget: combo
    
  - identifier: segment_gap
    title: Segment Gap
    type: integer
    description: >
      The space in pixels between the segments.
    mutable: yes
    readonly: no
    default: 10
    minimum: 0
    maximum: 100
    unit: pixels
    
  - identifier: bands
    title: Points
    type: integer
    description: >
      The number of bands to draw in the spectrum. Each band shows up as a data 
      point in the graph.
    mutable: yes
    readonly: no
    default: 31
    
  - identifier: frequency_low
    title: Low Frequency
    type: integer
    description: >
      The low end of the frequency range to be used for the graph.
      motion.
    mutable: yes
    readonly: no
    default: 20
    unit: Hz
    
  - identifier: frequency_high
    title: High Frequency
    type: integer
    description: >
      The high end of the frequency range to be used for the graph. 
      motion.
    mutable: yes
    readonly: no
    default: 20000
    unit: Hz
    
  - identifier: threshold
    title: Level Threshold
    type: float
    description: >
      The minimum amplitude of sound that must occur within the frequency range
      to cause the value to be applied.
      motion.
    mutable: yes
    readonly: no
    default: -30
    minimum: -100
    maximum: 0
    unit: dB
    
  - identifier: segments
    title: Segments
    type: integer
    description: >
      The number of segments to draw if the graph type is "segment".
    mutable: yes
    readonly: no
    default: 10
    minimum: 2
    maximum: 100
    
  - identifier: window_size
    title: Window Size
    type: integer
    description: >
      The number of samples that the FFT will be performed on. If
      window_size is less than the number of samples in a frame, extra samples 
      will be ignored. If window_size is more than the number of samples in a 
      frame, samples will be buffered from previous frames to fill the window.
      The buffering is performed as a sliding window so that the most recent 
      samples are always transformed.
    mutable: no
    readonly: no
    default: 2048