Skip to content

WaveFileSink

Overview

Captures the input wire audio samples and writes it into a multi-channel output .wav file

Discussion

The WaveFileSink module captures audio samples from the input pin and writes them to the output .wav file specified by the user. File writing happens in the deferred processing thread, if .isActive flag is TRUE, so as to not interrupt real-time processing.

This module is only applicable on targets that support a file system.

ARGUMENTS

This module has one input pin. The output .wav will capture all the channels from the input pin, and will use the sample rate derived the input pin. The sampleSize (either 2 or 4 bytes) of the recorded audio is a module argument. The module is designed to work with both Native and Linux targets. The directoryName and baseName of the output.wav can also be specified as module arguments.

  • e.g.: if the baseName:RECORD then output .wav = RECORD.wav).

By prefixing or postfixing to the baseName, the output .wav file will be created with timestamp information appended to the file name.

  • e.g.: if # is prefixed in the baseName:#-RECORD then output .wav = YYYYMONDAY_HHMMSS-RECORD.wav).

  • e.g.: if # is postfixed in the baseName:RECORD-# then output .wav = RECORD-YYYYMONDAY_HHMMSS.wav).

Also note that the absolute paths for directoryName are not portable across Windows and Linux, but relative paths are.

  • e.g.: Linux full directoryName : /home/pi/AudioWeaver-8.0.0-Linux/AWECore/Audio will not work in Windows environment, and Windows full directoryName \Audio\ will not work in the Linux environment.

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

  • Note that the current working directory in Windows is: \Bin\win32-vc142-rel (32 bit builds) or \Bin\x64-vc142-rel(64 bit builds).

  • The current working directory in Linux is the directory where the application is executed from.

  • e.g.: if the package (AWECoreOS) is extracted on the target and the sample application Libtester is executed from ~/AWECoreOS/Bin, then the Bin directory is the current working directory in this case.

Please note that there is a max limit on the file name including directory name up to 511 chatacters. If the provided file name is bigger than max supported, an error code of -122 is returned in .errorCode.

The blockSize of the module will be derived from the input pin.

The cache size argument defines the size of the cache buffer that is allocated by the module to store the audio so that the fwrite can occurred in the deferred set call. If the cache size is N, then the deferred set will be called when there are at least N/2 samples in the buffer. This is a per channel configuration, internally the module will allocate a buffer that is cache size * number of channels. If the user notices that the overRunCtr counter is incrementing, indicating insufficient caching, then try increasing the cache size until no more over runs occur.

SUPPORTED FILE FORMATS

The WaveFileSink module creates an output .wav file of the following format:

  • Chunk ID : RIFF

  • WAVE ID : WAVE

  • sub chunk1 ID : fmt

  • sub chunk2 ID : data

  • Format Tag : PCM (1)

INSPECTOR DETAILS

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

  • initDone : 0 indicates that fopen() failed, 1 indicates that fopen() was successful.

  • isActive : Used to control start/pause. On pause, the module stops capturing the audio data from the input pin. Write data continues until the circular buffer is empty.

  • overRunCtr : This counter increments when the file was not written quickly enough. Increase the cacheSize argument to prevent over runs.

  • errorCode : Captures errors that arise in the module C code. To help debug the configuration

ERROR CODES

Possible ERROR codes, reported (Inspector -> errorCode). The module uses the standard Audio Weaver errors found in the file Errors.h.

  • E_CANOPEN -41 : File fopen command failed (output.wav)

  • E_FILE_ALREADY_EXISTS -52 : File fopen command failed (output.wav) and the file is already open. Do you have multiple WaveFileSink modules all writing to the same file name?

  • E_IOERROR -45 : File fwrite command error (output.wav)

  • E_PARAMETER_ERROR -17 : The sampleSize argument is not a valid value

  • E_NOT_SUPPORTED -83 : No file system support

Module Pack

Advanced

ClassID

classID = 1416

Type Definition

typedef struct _ModuleWaveFileSink
{
ModuleInstanceDescriptor instance;            // Common Audio Weaver module instance structure
INT32 cacheSize;                              // The size of the buffer that is used to store the audio samples captured from the input pin before the deferred set call issues a fwrite, defined in terms number of samples per channel (CACHESIZE * NUMCHANNELS)
INT32 sampleSize;                             // Size of the sample to be stored in the file (2 bytes / 4 bytes)
INT32 isActive;                               // True means recording is active/started, false means recording is paused. Can be dynamically controlled in inspector
INT32 initDone;                               // State variable, indicates initialization done state. Appears on the inspector
INT32 readIndex;                              // Current read-pointer of the cache memory
INT32 writeIndex;                             // Current write-pointer of the cache memory
INT32 fillLevel;                              // Current fill level in the cache
INT32 overRunCtr;                             // Counts the number of over runs, incremented when the cache overflows. Appears on the inspector
INT32 errorCode;                              // Captures errors that could arise in the module C code. Appears on the inspector 
INT32 totalNoSamples;                         // Total number of samples written into the output.wav
INT32 fullFileSize;                           // Size of the array to hold the full file path for the output.wav file to be created
INT32* fullFileName;                          // Complete file path for the output.wav file to be created
fract32* cache;                               // The buffer used to store the audio samples from the input wire before the deferred set call issues a fwrite
void * inFile;                                // File pointer to access the output wav file
void * actualFileName;                        // Pointer to hold actual file name along with the path
} ModuleWaveFileSinkClass;

Variables

Properties

Name Type Usage isHidden Default Value Range Units
cacheSize int const 0 2048 Unrestricted
sampleSize int const 0 2 Unrestricted
isActive int parameter 0 1 Unrestricted
initDone int state 0 0 Unrestricted
readIndex int state 0 0 Unrestricted
writeIndex int state 0 0 Unrestricted
fillLevel int state 0 0 Unrestricted
overRunCtr int state 0 0 Unrestricted
errorCode int state 0 0 Unrestricted
totalNoSamples int const 0 0 Unrestricted
fullFileSize int const 0 2 Unrestricted
fullFileName int* parameter 1 [1 x 2] Unrestricted
cache fract32* state 0 [0 x 0] Unrestricted
inFile void * const 0 Unrestricted
actualFileName void * const 0 Unrestricted

Pins

Input Pins
Name in
Description Input audio
Data type fract32
Channel range Unrestricted
Block size range Unrestricted
Sample rate range Unrestricted
Complex support Real

Matlab Usage

File Name: wave_file_sink_module.m 
 M = wave_file_sink_module(NAME, DIRECTORYNAME, BASENAME, CACHESIZE, SAMPLESIZE) 
 WaveFileSink module captures the input data from the input pin and stores 
 it on to a output.wav (RIFF) file.  The audio data from the input pin is  
 stored to a buffer (cache) by the process function and periodically  
 written into the file in the deferred call.  Output .wav file will be a  
 wave file of PCM format only.  User configurable sample width of 2 or 4  
 bytes for output .wav.  Floating point data not supported. The data on  
 the input pin is always of the type Fract32.  This module is designed to  
 work on Native and Linux targets.

Copyright (c) 2026 DSP Concepts, Inc.