Filters (APL for Audio)

Filters change the characteristics of a streaming audio clip, such as volume levels, duration, and play positions. You have the option to apply filters sequentially, by using the output of one filter as the input of another. For example, you can apply the Trim filter to an audio clip, and then have the truncated clip used as input for the FadeIn filter.

About applying filters

Alexa applies filters in the order that you specify, providing output of one filter as input to the next. For example, a filter that fades audio followed by a filter that truncates audio produces a different result than a filter that truncates audio followed by a filter that fades audio.

Individual properties of a filter support data binding. Alexa evaluates filters in a data-binding context, which is the source context that defined the filter.

The filter evaluation process has the following steps:

  1. Alexa evaluates the when property. If the when property evaluates to false, Alexa skips the filter, and then iterates to the next filter in the array.

  2. Alexa evaluates the type property of the filter. If Alexa doesn't recognize the type value, Alexa skips to the next filter in the array.

Filter types

APL for Audio supports two different kinds of filters:

  • Built-in – An APL built-in filter with a set of required properties, such as FadeIn. The following built-in filters are available:
    • FadeIn – Ramps up the volume of an audio clip from 0 percent of its volume to its input volume.
    • FadeOut – Ramps down the volume of an audio clip from its input volume to 0 percent of its volume.
    • Repeat – Repeats the audio clip a specified number of times.
    • Trim – Starts or stops playback of an audio clip at a specific point.
    • Volume – Adjusts the volume of an audio clip by the specified amount.
  • User-defined – User-defined filters inflate into an array of filters to apply. Alexa applies the filters in the array according to the rules described in About applying filters. Playback resumes after the filters are applied.

Standard filter properties

The following table shows the properties that all audio filters support.

Property Type Default/Required? Description
description String "" Optional description you provide for this filter.
type String Required Type of filter. You must specify the type for all filters.
when Boolean true If true, apply the filter. If false, skip the filter.

FadeIn filter

Use the FadeIn filter to have an audio clip have a triangular/linear ramp up of its volume from 0 percent to its input.

The following table shows the properties that the FadeIn filter has in addition to the standard filter properties.

Property Type Default/Required? Description
duration Time Required Specifies the number of milliseconds (ms) for the volume to ramp up. If the duration is longer than the length of the audio clip, the ramp up applies for the entire provided duration and results in the audio clip never reaching max volume.

Example

Copied to clipboard.

{
  "type": "Audio",
  "source": "https://amazon.com/rainforestSoundEffect.mp3",
  "filter": [
    {
      "type": "FadeIn",
      "duration": 2000
    }
  ]
}

FadeOut filter

Use the FadeOut filter to have an audio clip have a triangular/linear ramp down of its volume from its input to 0%.

The following table shows the properties that the FadeOut filter has in addition to the standard filter properties.

Property Type Default/Required? Description
duration Time Required Specifies the number of milliseconds (ms) for the volume to ramp down. This property is expressed as a time unit. If the duration is longer than the length of the audio clip, the fade applies to the entire provided duration and results in the audio clip starting at a reduced volume.

Example

Copied to clipboard.

{
  "type": "Audio",
  "source": "https://amazon.com/rainforestSoundEffect.mp3",
  "filter": [
    {
      "type": "FadeOut",
      "duration": 2000
    }
  ]
}

Repeat filter

Use the Repeat filter to repeat an audio sample for a specified number of times.

The following table shows the properties that the Repeat filter has in addition to the standard filter properties.

Property Type Default Description
repeatCount number 0 Specifies how many times to repeat.

The repeatCount specifies how many times to repeat the audio clip. Alexa plays the clip the first time, then plays it again the specified number of times. For example, when repeatCount is 2, Alexa plays the clip a total of three times.

When you set repeatCount to a large number, Alexa limits the playback to the maximum supported content length for an APL for audio response.

Set repeatCount to -1 to repeat an infinite number of times, up to the maximum content length for an APL for audio response.

Example

This example shows an Audio component that plays a rain sound effect three times.

Copied to clipboard.

{
  "type": "Audio",
  "source": "soundbank://soundlibrary/nature/amzn_sfx_rain_01",
  "filter": [
    {
      "type": "Repeat",
      "repeatCount": 2
    }
  ]
}

Example of matching background audio to speech

You can combine the Repeat filter with the duration property on a component to match background audio to the exact length of another component, such as speech.

The following example sets the "rain on roof" sound effect to repeat an infinite number of times. The trimToParent setting on duration trims the resulting audio to match the length of the Speech component. The result repeatedly loops the sound effect for the exact duration of the speech.

Copied to clipboard.

{
  "type": "Mixer",
  "items": [
    {
      "type": "Speech",
      "content": "This is the text to speech. The rain on roof sound effect is just over two seconds. With the repeat filter set to -1 and duration set to trimToParent, Alexa loops the background audio repeatedly and then trims it to end when the text to speech ends."
    },
    {
      "type": "Audio",
      "filters": [
        {
          "type": "Repeat",
          "repeatCount": -1
        }
      ],
      "source": "soundbank://soundlibrary/nature/amzn_sfx_rain_on_roof_01",
      "duration": "trimToParent"
    }
  ]
}

Trim filter

Use the Trim filter to start playback of an audio clip at a specific point, to end playback at a specific point, or to do both.

The following table shows the properties that the Trim filter has in addition to the standard filter properties.

Property Type Default/Required? Description
end Time null Specifies the time for the audio clip to end. Everything following this time is trimmed off. If you don't provide this property or it equals null, the audio clip plays for the rest of its duration.
start Time 0 The time when the audio starts. Everything preceding this time is trimmed off.

Example

Copied to clipboard.

{
  "type": "Audio",
  "source": "https://amazon.com/rainforestSoundEffect.mp3",
  "filter": [
    {
      "type": "Trim",
      "start": 2000,
      "end": 9000
    }
  ]
}

Volume filter

Use the Volume filter to increase or decrease the volume of an audio clip by a defined amount.

The following table shows the properties that the Volume filter has in addition to the standard filter properties.

Property Type Default/Required? Description
amount number or string Required Specifies the proportion to adjust the volume of the audio clip. The amount can be either a number or a percentage. The output volume equals the audio clip volume multiplied by the amount.

Volume adjustments are relative to the original volume of the clip. The adjustments don't change device settings. For example, 100% is the original clip volume and 200% is twice the normal volume.

Example with volume as a number

Copied to clipboard.

{
  "type": "Audio",
  "source": "https://amazon.com/rainforestSoundEffect.mp3",
  "filter": [
    {
      "type": "Volume",
      "amount": 0.5
    }
  ]
}

Example with volume as a percentage

Copied to clipboard.

{
  "type": "Audio",
  "source": "https://amazon.com/rainforestSoundEffect.mp3",
  "filter": [
    {
      "type": "Volume",
      "amount": "50%"
    }
  ]
}