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 filter application

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 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 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. For more details, see Filter types.

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:
    • Trim filter – Starts or stops playback of an audio clip at a specific point.
    • FadeIn filter – Ramps up the volume of an audio clip from 0% of its volume from to its input volume.
    • FadeOut filter – Ramps down the volume of an audio clip from its input volume to 0% of its volume.
    • Volume filter – 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 Filter application rules. Playback resumes after all the filter application completes.

Standard filter properties

All audio filters support the following properties:

Property Type Default/Required? Description
description String "" Optional developer-provided description of this filter.
type String REQUIRED Type of filter. Must be specified for all filters.
when Boolean true If true, apply the filter. If false, skip the filter.

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 Trim filter has the following properties 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 this property is not provided or equals null, the audio clip plays for the rest of its duration.
start Time 0 The time when the audio will start. Everything preceeding this time is trimmed off.

Example

Copied to clipboard.

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

FadeIn filter

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

The FadeIn filter has the following properties in addition to the standard filter properties:

Property Type Default/Required? Description
duration Time REQUIRED Specifies the number of milliseconds 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 FadeOut filter has the following properties in addition to the standard filter properties:

Property Type Default/Required? Description
duration Time REQUIRED Specifies the number of milliseconds 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 for 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
    }
  ]
}

Volume filter

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

The Volume filter has the following properties 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.

There isn't an upper limit on the volume filter. For best results, be sure to test large volume increases in the authoring tool and verify that the clip sounds as you expect.

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%"
    }
  ]
}
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment