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:
-
Alexa evaluates the
when
property. If thewhen
property evaluates tofalse
, Alexa skips the filter and iterates to the next filter in the array. -
Alexa evaluates the
type
property of the filter. If Alexa doesn't recognize thetype
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
{
"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
{
"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
{
"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
{
"type": "Audio",
"source": "https://amazon.com/rainforestSoundEffect.mp3",
"filter": [
{
"type": "Volume",
"amount": 0.5
}
]
}
Example with volume as a percentage
{
"type": "Audio",
"source": "https://amazon.com/rainforestSoundEffect.mp3",
"filter": [
{
"type": "Volume",
"amount": "50%"
}
]
}