Audio
Validates that a file is a valid audio file that meets certain constraints
(duration, bitrate, sample rate, number of channels, etc.). It extends the
File constraint, so you can also use all
its options (e.g. maxSize).
| Applies to | property or method |
| Class | Audio |
| Validator | AudioValidator |
8.2
The Audio constraint was introduced in Symfony 8.2.
Basic Usage
This constraint is most commonly used on a property that stores an audio file as a File object. For example, suppose you're creating a podcast platform and want to validate uploaded episodes:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
// src/Entity/PodcastEpisode.php
namespace App\Entity;
use Symfony\Component\HttpFoundation\File\File;
use Symfony\Component\Validator\Constraints as Assert;
class PodcastEpisode
{
#[Assert\Audio(
maxSize: '200M',
maxDuration: 7200,
minBitrate: 64000,
allowedSampleRates: [44100, 48000],
maxChannels: 2,
)]
private File $audioFile;
}
The constraint reads the actual characteristics of the file with ffprobe, so
it doesn't rely only on the file extension or its media type. When you don't set
any of the audio-specific options, the constraint only performs the checks of
the File constraint and doesn't run ffprobe.
Warning
The audio-specific options require the ffprobe binary, which is part of
the FFmpeg package, and the
Process component.
Options
allowedCodecs
type: array default: []
Defines which audio codecs are allowed, using the codec names reported by
ffprobe (e.g. mp3, aac, opus, flac, pcm_s16le). The
comparison is case-insensitive. An empty list allows all codecs. This example
only allows MP3 and AAC audio:
1 2 3 4 5 6 7 8 9 10 11 12 13
// src/Entity/PodcastEpisode.php
namespace App\Entity;
use Symfony\Component\HttpFoundation\File\File;
use Symfony\Component\Validator\Constraints as Assert;
class PodcastEpisode
{
#[Assert\Audio(
allowedCodecs: ['mp3', 'aac'],
)]
private File $audioFile;
}
allowedContainers
type: array default: []
Defines which audio container formats are allowed, using the format names
reported by ffprobe (e.g. mp3, ogg, wav, flac, mp4). The
comparison is case-insensitive. An empty list allows all containers.
ffprobe can report several names for a format (e.g.
mov,mp4,m4a,3gp,3g2,mj2 for an M4A file). In that case, the file is valid if
any of those names is allowed. This example only allows MP3 and Ogg files:
1 2 3 4 5 6 7 8 9 10 11 12 13
// src/Entity/PodcastEpisode.php
namespace App\Entity;
use Symfony\Component\HttpFoundation\File\File;
use Symfony\Component\Validator\Constraints as Assert;
class PodcastEpisode
{
#[Assert\Audio(
allowedContainers: ['mp3', 'ogg'],
)]
private File $audioFile;
}
allowedSampleRates
type: array default: []
If set, the sample rate of the audio file must be one of these values in hertz
(e.g. [44100, 48000]).
groups
type: array | string default: null
It defines the validation group or groups of this constraint. Read more about validation groups.
maxBitrate
type: integer
If set, the bitrate of the audio file must be less than or equal to this value
in bits per second. It must be greater than 0.
maxChannels
type: integer
If set, the number of channels of the audio file must be less than or equal to
this value (e.g. 1 to only allow mono files). It must be greater than 0.
maxDuration
type: integer | float
If set, the duration of the audio file must be less than or equal to this value
in seconds. It must be greater than 0.
mimeTypes
type: array or string default: audio/*
See the File mimeTypes option for a description of this option.
minBitrate
type: integer
If set, the bitrate of the audio file must be greater than or equal to this value in bits per second. It can't be negative.
minChannels
type: integer
If set, the number of channels of the audio file must be greater than or equal
to this value (e.g. 2 to reject mono files). It can't be negative.
minDuration
type: integer | float
If set, the duration of the audio file must be greater than or equal to this value in seconds. It can't be negative.
payload
type: mixed default: null
This option can be used to attach arbitrary domain-specific data to a constraint. The configured payload is not used by the Validator component, but its processing is completely up to you.
For example, you may want to use several error levels to present failed constraints differently in the front-end depending on the severity of the error.
Messages
bitrateNotDetectedMessage
type: string default: The bitrate of the audio could not be detected.
The message displayed if ffprobe can't detect the bitrate of the audio and
the minBitrate or maxBitrate option is set.
channelsNotDetectedMessage
type: string default: The number of audio channels could not be detected.
The message displayed if ffprobe can't detect the number of channels of the
audio and the minChannels or maxChannels option is set.
corruptedMessage
type: string default: The audio file is corrupted.
The message displayed if the audio file is corrupted and ffprobe can't read
it.
durationNotDetectedMessage
type: string default: The duration of the audio could not be detected.
The message displayed if ffprobe can't detect the duration of the audio and
the minDuration or maxDuration option is set.
maxBitrateMessage
type: string default: The audio bitrate is too high ({{ bitrate }} bps). Allowed maximum bitrate is {{ max_bitrate }} bps.
The message displayed if the bitrate of the audio exceeds maxBitrate.
You can use the following parameters in this message:
| Parameter | Description |
|---|---|
{{ bitrate }} |
The current bitrate of the audio in bits per second |
{{ max_bitrate }} |
The maximum allowed bitrate in bits per second |
maxChannelsMessage
type: string default: The audio has too many channels ({{ channels }}). Maximum amount expected is {{ max_channels }}.
The message displayed if the number of channels of the audio exceeds maxChannels.
You can use the following parameters in this message:
| Parameter | Description |
|---|---|
{{ channels }} |
The current number of channels of the audio |
{{ max_channels }} |
The maximum allowed number of channels |
maxDurationMessage
type: string default: The audio is too long ({{ duration }} seconds). Allowed maximum duration is {{ max_duration }} seconds.
The message displayed if the duration of the audio exceeds maxDuration.
You can use the following parameters in this message:
| Parameter | Description |
|---|---|
{{ duration }} |
The current duration of the audio in seconds |
{{ max_duration }} |
The maximum allowed duration in seconds |
mimeTypesMessage
type: string default: This file is not a valid audio file.
The message displayed if the media type of the file is not a valid media type
per the mimeTypes option. If you set that option to a list without
audio/*, the default message becomes the one of the File constraint.
minBitrateMessage
type: string default: The audio bitrate is too low ({{ bitrate }} bps). Minimum bitrate expected is {{ min_bitrate }} bps.
The message displayed if the bitrate of the audio is less than minBitrate.
You can use the following parameters in this message:
| Parameter | Description |
|---|---|
{{ bitrate }} |
The current bitrate of the audio in bits per second |
{{ min_bitrate }} |
The minimum allowed bitrate in bits per second |
minChannelsMessage
type: string default: The audio has too few channels ({{ channels }}). Minimum amount expected is {{ min_channels }}.
The message displayed if the number of channels of the audio is less than minChannels.
You can use the following parameters in this message:
| Parameter | Description |
|---|---|
{{ channels }} |
The current number of channels of the audio |
{{ min_channels }} |
The minimum allowed number of channels |
minDurationMessage
type: string default: The audio is too short ({{ duration }} seconds). Minimum duration expected is {{ min_duration }} seconds.
The message displayed if the duration of the audio is less than minDuration.
You can use the following parameters in this message:
| Parameter | Description |
|---|---|
{{ duration }} |
The current duration of the audio in seconds |
{{ min_duration }} |
The minimum allowed duration in seconds |
multipleAudioStreamsMessage
type: string default: The audio contains multiple streams. Only one stream is allowed.
The message displayed if the file contains more than one audio stream.
noAudioStreamMessage
type: string default: The file does not contain any audio stream.
The message displayed if the file doesn't contain any audio stream (e.g. a video file without a soundtrack, when mimeTypes allows video files).
sampleRateNotDetectedMessage
type: string default: The sample rate of the audio could not be detected.
The message displayed if ffprobe can't detect the sample rate of the audio
and the allowedSampleRates option is set.
unsupportedCodecMessage
type: string default: Unsupported audio codec "{{ codec }}".
The message displayed if the audio uses a codec that is not in the allowedCodecs list.
You can use the following parameters in this message:
| Parameter | Description |
|---|---|
{{ codec }} |
The codec of the audio |
unsupportedContainerMessage
type: string default: Unsupported audio container "{{ container }}".
The message displayed if the audio uses a container format that is not in the allowedContainers list.
You can use the following parameters in this message:
| Parameter | Description |
|---|---|
{{ container }} |
The container format of the audio |
unsupportedSampleRateMessage
type: string default: Unsupported audio sample rate ({{ sample_rate }} Hz).
The message displayed if the sample rate of the audio is not in the allowedSampleRates list.
You can use the following parameters in this message:
| Parameter | Description |
|---|---|
{{ sample_rate }} |
The sample rate of the audio in hertz |