The FilePlayer audio object is used to read the audio content from a file and present them in real time on the output channels. Additionally, this audio object can also be used to add or mix the file content with the audio fed into the input channel buffers of this object.
A background thread is used to read the file contents in bulk and place them in the intermediate cache buffer, while in the main thread, the required audio data (of framework block length size) is copied from the intermediate cache buffer to the output channel buffers. The background thread periodically checks for the number of samples available in the cache buffer and replenishes the needed files.
Use Case: The FilePlayer has the following use case.
- Stream WAV files from the local filesystem in real-time
- Resample to the target sample rate if needed
- Option to support play speed from 0.1 to 10
- Option to repeat playback in loop mode indefinitely or for a fixed number of times
- Option to insert a configurable silence period in between file playback in loop mode
- Shall support option to disable/enable pitch shifting (linear and polyphase)
- Shall support mixing the file content with the output of another AO
- Support a configurable number of output channels (up to 16)
- Configurable cache to suit platform capabilities and requirements
- Support WAV / PCM Files configurable during design time. Furthermore, WAV / PCM files with all of these data types are supported.
- 8 bit mu-law
- 8 bit A-law
- 16 bit integer
- 24 bit integer
- 32 bit float
Internally, all samples are converted to 32-bit floating-point numbers. For both the 8 bit command formats, the conversion is done via a lookup table with 256 entries. This look-up table is filled based on the encoding format.
File Player Properties
| Properties |
Descriptions |
| # of channels |
The number of channels are configurable.
- Range: 1 to 16
- Data type: Unsigned Short
- The default value is set to 1.
|
| Display Name |
Display the name of the FilePlayer audio object in signal flow design. It can be changed based on the intended usage of the object. |
| Object mode |
The object has two modes.
|
| Additional Parameters |
- Pitch shifting options
- Add file data with inputs
- Cache Buffer Config (multi-dimensional)
- File Type
- Data format (only for PCM mode)
- Content Sample Rate (only for PCM mode)
- Select Interval Type
- Enable Loop count
|
Mode
The FilePlayer audio object supports two different modes of operation. The audio object can read from both WAV and PCM files.
- WAV (Default): The WAV file contains a header that has the necessary details about the stored audio content in the file
- PCM: The PCM file contains only the audio data, and the details such as sampling rate and data format of the stored audio data must be provided separately.
Additional Parameters
The FilePlayer audio object can be configured with the following additional parameters.
| Parameter |
Descriptions |
| Pitch shifting |
This feature is provided to increase or decrease the playing speed (sample rate at which the content is played).
- 0 – Disabled (Default)
- 1 – Polyphase Resampling Enabled
- 2 – Linear Interpolation Enabled
|
 |
| Add file data with inputs |
If this feature is enabled, an equal number of input channels will be supported.
Add the content of the audio file with the output of the previous AO to generate the output.
- 0 – Disabled (Default)
- 1 – Enabled
By default, the AO will have only output channels and no input channels. |
 |
| CacheBuffer Config |
This is a three-dimensional additional parameter.
1. Cache buffer: Size of internal memory to be allocated for reading data in the background thread.
- Range: 256 to 16384 float words per channel with power of 2.
- Default: 16384 float words per channel.
If the background thread is having significantly lower priority, the buffer underrun is likely to occur for lower cache sizes. In such cases, the cache buffer size shall be increased.
2. Max samples/call: Maximum number of samples that can be read in a single background call for a channel. This helps to control the peak load in the background thread while configuring a new channel
- Range: 256 to Cache buffer size (# 1)
- Default: 16384 samples
3. Min samples/call: Minimum number of samples that can be read in a single read API (platform) call for a channel. This helps to control the call overhead due to frequent call of read API
- Range: 1 to least of the below two:
- Half of the Cache buffer size (#1)
- Max samples/call (# 2)
- Default: 8192 samples
All the above range restrictions are applied by the FilePlayer AO while booting. These range restrictions cannot be enforced by the GTT because, with a multi-dimensional additional parameter, for all the parameters, GTT uses the single min/max values available in the toolbox. Hence, the SFD designer is advised to ensure the limits are honoured (as seen in the side note of the pop-up window).
|
 |
| File Type |
The object supports the following files:
- 0 – Single Multichannel file (Default)
- 1 – Multiple Mono files
|
 |
| Data format (only for PCM mode) |
- 0 – Invalid
- 1 – 8 bit A-Law companded
- 2 – 8 bit Mu-Law companded
- 3 – 16 bit integer
- 4 – 24 bit integer
- 5 – 32 bit Float (Default)
|
 |
| Content Sample Rate (only for PCM mode) |
All sample rates supported by the framework shall be supported
The default sample rate is 48000 Hz. |
 |
| Select Interval type |
The way the interval duration is to be used can be configured here.
- 0 – Playback and silence (Default) – used in Intermittent mode
- 1 – Silence only – used in Loop mode
- 2 – Disable inserting silence between playback
|
 |
| Enable Loop count |
This parameter is used to configure if the loop count feature is to be supported.
- 0 – Disable Loop count (Default) – repeats indefinitely in loop mode
- 1 – Enable Loop count – repeat only for the number of times specified in the loop count tuning parameter or control input
|
 |
Tuning Parameters
The tuning parameters of the FilePlayer audio object support the following parameters.
- Ramping Params Sub block: This subblock has ramping-related tuning parameters applicable to all the channels. All the parameters in this sub-block as stored as unsigned integers.
- File_Config sub block: There is a separate file configuration sub block for each file. In SingleMultiChannel mode, only one sub-block is present whose parameters are applicable for all the channels. In MultipleMonoFiles mode, each file has its own sub-block where the parameters in each sub-block is applicable for the respective mono channel.
| Parameters |
Description |
Unit |
Range |
Default |
Ramping Params Sub block
|
| Fade-in time |
Applied for control change from Stop / Pause to Play
This period needs to be less than the file playback duration.
|
ms |
0 to 1000 |
100 |
| Fade-in type |
Linear type only is implemented
- 0 – Linear
- 1 – Exponential (not implemented)
|
None |
0 or 1 (Enum) |
0 |
| Fade-out time |
Applied for control change from Play to Stop / Pause.
The sum of fade-out delay and fade-out time needs to be less than the file playback duration.
|
ms |
0 to 1000 |
100 |
| Fade-out type |
Linear type only is implemented
- 0 – Linear
- 1 – Exponential (not implemented)
|
None |
0 or 1 (Enum) |
0 |
| Fade-out delay |
Delay period before starting fade-out process.
The sum of fade-out delay and fade-out time needs to be less than the file playback duration.
|
ms |
0 or 100 |
0 |
| Quick Fade-out time |
Applied when play command is received during fade-out or fade-out delay phase to quickly end the fade-out phase and start playback. Also quick fade-out is applied only when this value is less than fade-out time. By default, this feature is disabled as the default value is not less than the fade-out time. Only linear ramping is applied. |
ms |
0 to 1000 |
1000 |
| Pitch ramp time |
This parameter is available only when pitch shifting is enabled and is applied for any change in play speed value.
This period needs to be less than the file playback duration.
|
ms |
0 to 100 |
0 |
| Pitch ramp type |
This parameter is available only when pitch shifting is enabled. Linear type only is implemented.
- 0 – Linear
- 1 – Exponential (not implemented)
|
None |
0 or 1 (Enum) |
0 |
| File_Config sub block |
| File ID |
The files shall be placed in the device folder using FileController. |
None |
1 to 255
Data Type: Unsigned Integer |
1 |
| Play Setup |
- 1 – One Shot mode
- 2 – Loop mode
- 3 – Intermittent mode
- 4 – Reverse One Shot
- 3 – Reverse Loop
|
None |
1 to 5 (Enum)
Data Type: Unsigned Integer |
1 |
| Start Position |
Start position in percentage from where file will be played. In LOOP mode, this is applicable only at the start of the play and not on every loop back |
None |
0 to 99.99
Data Type: Float |
0 |
| Function |
- 1 – STOP
- 2 – PLAY
- 3 – RESET (STOP and PLAY)
- 4 – PAUSE
|
None |
1 to 4 (Enum)
Data Type: Unsigned Integer |
1 |
| Interval*
or
Silence
|
This parameter is available only when the interval type is not disabled in the ‘Select Interval Type’ additional parameter. Based on the option chosen in the additional parameter, one of the following two parameters will be available: Interval OR Silence
Interval: When ‘Select Interval Type’ = 0.
This is applicable only in Intermittent mode. This is the interval period at which the file will be played from the beginning periodically.
Silence: When ‘Select Interval Type’ = 1.
This is applicable only in Loop mode. This is the silence period inserted after each file playback. When the parameter value is zero, the loopback is seamless. |
Interval: s
Silence: ms |
Interval:
- 0.01 to 1000
- Data Type: Float
Silence:
- 0 to 1000
- Data Type: Unsigned Int
|
Interval: 10
Silence: 0 |
| Loop Count |
This parameter is available only when Loop count is enabled in the additional parameter. If not enabled, the file playback is repeated indefinitely.
Also, this parameter is applicable only in loop mode. If the value is zero, the file playback is repeated indefinitely; else the file playback is repeated for the given number of times. When in loop play mode, this parameter value is applied only when the AO is in stop state and not when it is in play state. |
None |
0 to 10000
Data Type: Unsigned Int
|
0 |
| Play Speed** |
This is available only when pitch shifting is enabled. This is the play speed at which the file is played |
None |
0.1 to 10
Data Type: Float |
1 |
* The interval period normally shall be greater than the waveform playback duration. If the interval is less than or equal to the waveform playback duration, glitch / pop noise with a short mute period is present.
** Playback Duration = File Duration / Play Speed
State Parameters
The state parameters of the FilePlayer audio object support the following parameters.
- Function State Subblock: This subblock has the function state parameter for each file. This parameter is used to configure and readback the present function state of the given channel(s). In SingleMultiChannel mode, only one state parameter is present that is applicable for all the channels. In MultipleMonoFiles mode, each file has its own state parameter applicable for the respective mono channel.
- File State Subblock: This subblock has the file state parameter for each file. This parameter is used only to readback the present file state of the given file(s) and any parameter change is ignored. In SingleMultiChannel mode, only one state parameter is present for the given file. In MultipleMonoFiles mode, each file has its own state parameter.
| State parameters |
Parameters |
Description |
Unit |
Range |
Default |
| Function State Subblock |
Function_Ch |
- 1 – STOP
- 2 – PLAY
- 3 – RESET (STOP and PLAY)
- 4 – PAUSE
|
None |
1 to 4 (Enum)
Data Type: Unsigned Integer |
1 |
| File State Subblock |
File_State |
This reflects the present file status.
- 0 – FILEPLAYER_IDLE
- 1 – FILE_READY
- 2 – FILE_PLAY_ACTIVE
- 3 – FILE_STOPPED
- 4 – FILE_OPEN_ERROR
- 5 – FILE_PAUSED
|
None |
0 to 5 (Enum)
Data Type: Unsigned Integer |
0 |
Control Interface
Control Inputs: The FilePlayer has the following Control Inputs.
- Block Control: There are FOUR control pins under this block control pin. For SingleMultiChannel mode, only one set of block control input needs to be sent. For Multiple Mono mode, for each channel, a set of block controls needs to be sent separately.
- Function Control Pins: This control pin is used to change the function of the AO. For AOs configured in Single Multichannel mode, only one (N = 1) control input pin will be available applicable to all the channels. For AOs configured in Multiple Mono mode with N channels, there will be an equal number (N) of control inputs for each file (channel).
- Interval / Silence Control Pins: Only one of them – Interval or Silence pin – can be made available based on the configuration in the additional parameter – ‘Select Interval Type’. For AOs configured in Single Multichannel mode, only one (N = 1) control input pin will be available, applicable to all the channels. For AOs configured in Multiple Mono mode with N channels, there will be an equal number (N) of control inputs for each file (channel).
The interval control pin is applicable only in INTERMITTENT play mode and is used to change the interval period of the playback.
Silence control pin is applicable only in LOOP play mode and is used to change the required silence period after each file playback.
- Loop Count Pins: These pins are available only when the loop count feature is enabled in the additional configuration parameter. If it is not configured, the file playback is repeated indefinitely.
For AOs configured in Single Multichannel mode, only one (N = 1) control input pin will be available, applicable to all the channels. For AOs configured in Multiple Mono mode with N channels, there will be an equal number (N) of control inputs for each file (channel).
- Pitch Control Pins: This control pin(s) is/are available only when pitch shifting is enabled and is used to change the play speed of waveform playback. For AOs configured in Single Multichannel mode, only one (N = 1) control input pin will be available that is applicable to all the channels. For AOs configured in Multiple Mono mode with N channels, there will be equal number (N) of control inputs for each file (channel).
| Control Input |
Parameter |
Description |
Size in Float Words |
Range |
| Block Control |
Channel ID |
Channel ID to associate with each output channel. |
1 of 4 |
1 to 16 |
| File ID |
The files shall be sent through the FileController. |
2 of 4 |
1 to 255 |
| File Setup |
- 1 – One Shot mode
- 2 – Loop mode
- 3 – Intermittent mode (used only when ‘Select Interval type’ additional parameter is configured to 0 (Playback and Silence)
- 4 – Reverse One Shot
- 5 – Reverse Loop
|
3 of 4 |
1 to 5 |
| Start Position |
Start position in percentage from where file will be played. |
4 of 4 |
0 to 99.99 |
| Function Control Pins |
Function |
- 1. STOP (default on boot-up)
- 2. PLAY
- 3. RESET (STOP followed by PLAY)
- 4. PAUSE
|
N |
1 to 4 |
| Interval / Silence Control Pins |
Interval |
This is the interval period at which the file will be played from the beginning periodically. |
N |
0.01 to 1000 s |
| Silence |
This is the silence period inserted in between consecutive file playback. |
N |
0 to 1000 ms |
| Loop Count Pins |
Loop count |
This is the number of times the file playback is to be repeated. If the value is zero, the playback is repeated indefinitely. When in loop play mode, this control value is applied only when the AO is in stop state and not when it is in play state. |
N |
0 to 10000 |
| Pitch Control Pins |
Play Speed |
This is the play speed at which the file is played.
The control input is in terms of play speed. |
N |
0.1 to 10 |
Control Outputs: There are two control output pins – either two single control pins or two block control pins.
- When the AO is configured in Single Multichannel mode, two single control (N = 1) pins are available for the control outputs listed below.
- When the AO is configured in Multiple Mono mode with N channels, two block control (N) pins are available for the control outputs listed below.
| Control Output |
Description |
Size in Float Words |
Range |
| Play Position |
During active playback, for every audio interrupt, the AO outputs the play position in terms of percentage covered in the file. |
N |
0 to 99.99 |
| File State
|
Whenever there is a change in the file status, the AO outputs the file state:
- 0 – FILEPLAYER_IDLE
- 1 – FILE_READY
- 2 – FILE_PLAY_ACTIVE
- 3 – FILE_STOPPED
- 4 – FILE_OPEN_ERROR
- 5 – FILE_PAUSED
|
N |
0 to 5 |
– In Single Multichannel file mode, a mono file can also be played.
– If a WAV file with content in unsupported format is configured, the file will not be opened. In PCM files, the format configured in the additional parameter is applied on the files.
– In Multiple Mono file mode, all the files need to be mono files. In WAV mode, if the file is seen having more than 1 channel, that file will be ignored. In PCM mode, the file will be taken as a mono file and played leading to improper output.
– In Multiple Mono file mode, all the mono files need to be in the same data format and sampling rate. If files with different data format are used, the data format of the last configured file will be considered and the same will be applied to all other mono files leading to improper output.
– The FilePlayer audio object can be configured with multiple channels. The channel count of the object and the number of channels in the wav file may differ. Error message is returned if extra channels are present in the audio file. If extra channels are configured in the object, those extra channels are filled with silence.
– It is recommended to configure the sound card block length to less than the cache buffer size under Sound Card Configuration while using IVP. It is recommended to use 1024 as the minimum cache size on IVP.
– The actual memory required for the supporting the intermediate cache buffer size will be slightly more than the size specified in the additional parameters as it is required to store extra data (of polyphase filter order) for supporting filtering. The memory latency table shall be referred for exact memory requirements.
– To configure the cache as ping-pong buffers, the max samples/call and min samples/call in the additional parameter shall be set to half of the cache buffer size.
– To configure the cache as circular buffer, the min samples/call in the additional parameter shall be set to 1.
– In cases with low intermediate cache buffer size, the background thread need to run frequently to replenish the data available in the cache buffer. If distortion is observed with low cache size, buffer underrun could be the cause and background thread shall be moved to higher priority or the cache buffer size shall be increased.
– In a Single Multichannel file, let the number of channels present in the file content be M and the number of channels configured for the object be N.
In WAV mode:
– If M = N, all the N channels will be played with the file content.
– If M < N, first M channels buffers will be populated with the file content and the remaining N-M channels will be muted.
– If M > N, none of the channels will be played, and all channels will be muted.
In PCM mode:
– If M = N, all the N channels will be played properly with the file content.
-If M != N, the file will be taken as a N-channel file and played,d leading to improper output.
Native Panel
The FilePlayer audio object does not support the native panel.
the delay calculated step value (based on max delay (ms)).