WaveFileSource

Overview

Opens and reads audio data from an input .wav file and streams it over the output wire

Discussion

The Wavefilesource module opens, reads, and streams the audio data from a .wav file over the module's output wire. File reading happens in the deferred processing thread so as not to interrupt real-time processing.

Arguments

This module, designed to work with Linux and Windows based targets, has one output pin with user configurable number of channels, sample rate and block sizes. And if there is a mismatch between configured values and number of channels and sample rate from the input .wav file, the user configurations take precedence. A channel matching mechanism is implemented internally as explained below for any mismatch in the number of channels in the .wav file and the numChannels module argument.

Example 1: if the user config number of channels = input .wav file = 3, then the output wire will have all the channels of input .wav file.

Example 2: if user config number of channels = 4 and input .wav file = 2, then the output wire will have the first 2 channels of the input .wav file and then last 2 channels will be all zeros.

Example 3: if user config number of channels = 1 and input .wav file = 2, then the output wire will have the first channel of the input .wav file only.

The sampleRate and blockSize arguments can be explicitly configured by the user, or the module will derive the values from the SYS_in pin.

The argument filePath gives the file name, with or without path, of the desired .wav file to load. If no path is provided, then the systems search path will be used to find the file. This is the AWE_SEARCH_PATH environmental variable in Linux, and the AWE AudioPath set by Designer if running on the Native Windows target. If the AWE_SEARCH_PATH environment variable is not set, then the module will look for the file in the current working directory.

e.g.: In Linux we can set the file search path using: export AWE_SEARCH_PATH=/home/pi/AudioWeaver-8.0.0-Linux/AWECore/Audio

e.g.: In Windows can set the search path in the INI file[AudioPath] Path section of the AWE_Server.ini file, or using the File->Set File Search Path menu item in Designer.

Also note that absolute file paths are not portable across Windows and Linux, but relate paths are.

e.g.: Linux full file path =/home/pi/AudioWeaver-8.0.0-Linux/AWECore/Audio/input.wav will not work in Windows environment, and Windows full file path C:\Repos\AWE8\AudioWeaver\Audio\input.wav will not work in the Linux environment, assuming that the input.wav exists in the path

e.g.: The following types of relative paths (relative to the current working directory) ../AWECore/Audio/input.wav or ..\AudioWeaver\Audio\input.wav are portable across Windows and Linux environment

The cache size argument defines the size of the cache buffer that should be allocated by the module to prefill the audio data in the deferred set call. This is a per channel configuration, so internally the module will allocate a buffer that is cache size * number of channels. If the user notices that the underRunCtr counter is incrementing, indicating insufficient caching, then try increasing the cache size until no more under runs occur. To avoid circular wrap of cache buffer with in a block, the size of the cache buffer is aligned with the block size. i.e. the allocated cache buffer size is ceil(cache size/blockSize) * blockSize * number of channels

The LoopFile argument will cause the module to loop through the file forever when enabled. If disabled, the file will play only once and then output zeros. This setting can't be changed dynamically.

Supported File Formats

The WaveFileSource can handle input .wav files only of the following format:

    Chunk ID : RIFF

    WAVE ID : WAVE

    sub chunk1 ID : fmt

    sub chunk2 ID : data

    Format Tag : PCM (1)

The WaveFileSource module can handle INT/FRACT 16/32 bit data types only. The 16 bit data types are internally converted to 32 bit data then streamed over the wire. The data type of the output wire is always FRACT32.

Inspector Details

On double clicking the module, an inspector will show up on the canvas with the following information:

initDone : 0 indicates that initialization failed, and 1 means that initialization was successful

isActive : Used to dynamically control play/pause. On Pause, the module stops reading the audio data from the input .wav file and transmits zeros on the wire

underRunCtr : This counter increments when the real-time system has not read enough data from the input file to supply to the module output. Increasing the module cacheSize can prevent underruns

errorCode : Any WARNING or ERROR code that results in the module is displayed here. Use to debug configuration issues

wavNumChannels : The number of audio channels in the input .wav. This is parsed in the module C code

wavSampleRate : The sample rate of the input .wav. This is parsed in the module C code

Error Codes

Possible WARNINGS codes, reported in (Inspector -> errorCode). In this situation the module completes initialization (initDone = 1) and continues to stream the audio data on the wire.

E_WAVE_FILE_CHANNEL_MISMATCH -12 : Mismatch between user configured channel configuration and number of channels from the input .wav file. Channel matching comes into play. The user can debug the condition by comparing the NUMCHANNELS argument against wavNumChannels

E_WAVE_FILE_SAMPLERATE_MISMATCH -13 : Mismatch between user sample rate configuration and sample rate of the input .wav file. The user can debug the condition by comparing the SAMPLERATE argument against wavSampleRate

Possible ERROR codes, reported (Inspector -> errorCode). In this situation the module stays uninitialized (initDone = 0) and zeros are streamed to the output wire.

E_WAVE_FILE_OPEN -1 : File fopen command error (input .wav)

E_WAVE_FILE_READ -2 : File fread command error (input .wav)

E_WAVE_FILE_WRITE -3 : File fwrite command error (input .wav)

E_WAVE_FILE_FSEEK -4 : File fseek command error (input .wav)

E_WAVE_INVALID_FILE_NAME -5 : Unable to find the file (input .wav). Please check the file name and search directories

E_WAVE_FILE_NOT_RIFF -6 : Input .wav chunkID not RIFF

E_WAVE_FILE_NOT_WAVE -7 : Input .wav Format not WAVE

E_WAVE_FILE_NOT_FMT -8 : Input .wav subchunk1ID not fmt

E_WAVE_FILE_AUDIO_FORMAT_UNSUPPORTED -9 : Input .wav file Audio format is not PCM (AudioFormat = 1)

E_WAVE_FILE_SUBCHUNK2ID_NOT_DATA -10 : Input .wav Format subchunk2ID not data

E_WAVE_FILE_SAMPLE_WIDTH_UNSUPPORTED -11 : Input .wav sample width unsupported (only 2 and 4 byte sample widths supported)

Type Definition

typedef struct _ModuleWaveFileSource
{
    ModuleInstanceDescriptor instance;            // Common Audio Weaver module instance structure
    UINT32 cacheSize;                             // The size of the buffer that is used to prefill the read audio samples in the deferred call, defined in terms number of samples (CACHESIZE * NUMCHANNELS)
    INT32 loopFile;                               // Play the audio file in a loop if enabled
    INT32 isActive;                               // True is playback is active, false is playback is paused. Can be dynamically controlled in inspector
    INT32 initDone;                               // State variable, indicates initialization done state. Appears on the inspector
    INT32 proNxtPass;                             // State variable, used to handling playback in a loop
    UINT32 readIndex;                             // Current read-pointer of the cache memory
    UINT32 writeIndex;                            // Current write-pointer of the cache memory
    UINT32 remSamples;                            // The number of samples remaining to be moved in the input.wav
    UINT32 fillLevel;                             // Current fill level in the cache
    UINT32 underRunCtr;                           // Counts the number of under runs, incremented when the cache does not have enough samples to output to wire. Appears on the inspector
    INT32 errorCode;                              // Captures errors/warnings that could arise in the module C code. Appears on the inspector
    UINT32 totalNoSamples;                        // State variable: total number of samples in the input.wav file
    UINT32 sampleWidth;                           // Sample width in terms of bytes of input .wav file
    INT32 wavNumChannels;                         // Number of channels of the input.wav file. Appears on the inspector
    FLOAT32 wavSampleRate;                        // Sample rate of the input.wav file. Appears on the inspector
    INT32 fullFileSize;                           // Length of the file name+path of the input.wav file name in bytes
    INT32* fullFileName;                          // Complete file path/file for the input.wav file
    fract32* cache;                               // The buffer that is used internally to prefill the read audio samples
    void * inFile;                                // File pointer to access the input wav file
} ModuleWaveFileSourceClass;

Variables

Properties

Pins

Output Pins

Name: out

Description: Output audio

Data type: fract32

MATLAB Usage

File Name: wave_file_source_module.m

 M = wave_file_source_module(NAME, WAVFILE, NUMCHANNELS, SR, BLOCKSIZE, CACHESIZE, LOOPFILE)
 Wavefilesource module opens, reads and streams the audio data from a input.wav file (RIFF) over the output wire. 
 The audio data is read periodically and prefilled into a buffer (cache) in the deferred call, for the process function to 
 stream it over the wire. 
 Supports multi-channel wave file of PCM format only. 
 This module is capable of reading from input file of the format 16 bit or 32 bit INT/FRACT32 data types.
 Floating point data not supported. The data on the output pin is always of the type Fract32.
 This module is designed to work on Native and Linux targets