You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
346 lines
11 KiB
346 lines
11 KiB
/*
|
|
* wavlib.h - simple WAV I/O library interface
|
|
* Copyright (C) 2006-2010 Francesco Romani <fromani at gmail dot com>
|
|
*
|
|
* This software is provided 'as-is', without any express or implied
|
|
* warranty. In no event will the authors be held liable for any damages
|
|
* arising from the use of this software.
|
|
*
|
|
* Permission is granted to anyone to use this software for any purpose,
|
|
* including commercial applications, and to alter it and redistribute it
|
|
* freely, subject to the following restrictions:
|
|
*
|
|
* 1. The origin of this software must not be misrepresented; you must not
|
|
* claim that you wrote the original software. If you use this software
|
|
* in a product, an acknowledgment in the product documentation would be
|
|
* appreciated but is not required.
|
|
* 2. Altered source versions must be plainly marked as such, and must not be
|
|
* misrepresented as being the original software.
|
|
* 3. This notice may not be removed or altered from any source distribution.
|
|
*/
|
|
|
|
#ifndef _WAVLIB_H_
|
|
#define _WAVLIB_H_
|
|
|
|
#ifdef HAVE_CONFIG_H
|
|
# include "config.h"
|
|
#endif
|
|
|
|
#include <sys/types.h>
|
|
#include <stdint.h>
|
|
|
|
/* transcode build system integration */
|
|
#ifdef WORDS_BIGENDIAN
|
|
#define WAV_BIG_ENDIAN 1
|
|
#else
|
|
#define WAV_LITTLE_ENDIAN 1
|
|
#endif
|
|
|
|
#define WAVLIB_VERSION "0.2.0"
|
|
#define WAVLIB_MAJOR 0
|
|
#define WAVLIB_MINOR 2
|
|
#define WAVLIB_PATCH 0
|
|
|
|
typedef enum {
|
|
WAV_READ = 1, /* open WAV file in read-only mode */
|
|
WAV_WRITE = 2, /* open WAV file in write-only mode */
|
|
WAV_PIPE = 4, /* cut SEEEKs */
|
|
} WAVMode;
|
|
|
|
typedef enum {
|
|
WAV_SUCCESS, /* no error so far */
|
|
WAV_NO_MEM, /* can't acquire requested amount of memory */
|
|
WAV_IO_ERROR, /* unable to read/write (often write) data */
|
|
WAV_BAD_FORMAT, /* acquired data doesn't seem wav-compliant */
|
|
WAV_BAD_PARAM, /* bad parameter for requested operation */
|
|
WAV_UNSUPPORTED, /* feature not yet supported by wavlib */
|
|
} WAVError;
|
|
|
|
typedef struct wav_ *WAV;
|
|
|
|
/*
|
|
* wav_open:
|
|
* open a WAVE file in given mode, either read-only or write-only,
|
|
* and associate a WAV descriptor to it.
|
|
*
|
|
* Parameters:
|
|
* filename: path of WAVE file to open.
|
|
* mode: mode to open WAVE file.
|
|
* Can be either WAV_READ (open read-only)
|
|
* or WAV_WRITE (open write only).
|
|
* WAV_PIPE can be OR'd with this parameter if given
|
|
* filename is a named pipe. This flag is honoured only
|
|
* if mode is WAV_READ.
|
|
* err: if not NULL, reason for error, if any, will be stored
|
|
* on WAVError pointed by this parameter.
|
|
*
|
|
* Return Value:
|
|
* a valid WAV descriptor if successfull, or NULL otherwise.
|
|
* Side effects:
|
|
* N/A
|
|
* Preconditions:
|
|
* N/A
|
|
* Postconditions:
|
|
* N/A
|
|
*/
|
|
WAV wav_open(const char *filename, WAVMode mode, WAVError *err);
|
|
|
|
/*
|
|
* wav_fdopen:
|
|
* attach a WAV descriptor to already open POSIX file descriptor.
|
|
*
|
|
* Parameters:
|
|
* fd: existing file descriptor; WAV descriptor will be attached here.
|
|
* mode: mode to open WAVE file.
|
|
* Can be either WAV_READ (open read-only)
|
|
* or WAV_WRITE (open write only).
|
|
* WAV_PIPE can be OR'd with this parameter if given
|
|
* filename is a pipe.
|
|
* value of 'mode' MUST be congruent with mode of given
|
|
* file descriptor.
|
|
* err: if not NULL, reason for error, if any, will be stored
|
|
* on WAVError pointed by this parameter.
|
|
*
|
|
* Return Value:
|
|
* a valid WAV descriptor if successfull, or NULL otherwise.
|
|
* Side effects:
|
|
* N/A
|
|
* Preconditions:
|
|
* N/A
|
|
* Postconditions:
|
|
* N/A
|
|
*/
|
|
WAV wav_fdopen(int fd, WAVMode mode, WAVError *err);
|
|
|
|
/*
|
|
* wav_close:
|
|
* close a WAV descriptor, freeing acquired resources,
|
|
*
|
|
* Parameters:
|
|
* handle: WAV descriptor to close
|
|
* Return Value:
|
|
* 0 if successfull, -1 otherwise
|
|
* Side effects:
|
|
* if error, error code is stored in WAV descritptor, and
|
|
* can be fetched using wav_last_error.
|
|
* If WAV descriptor was open using WAV_WRITE mode, WAVE
|
|
* header will be updated using wav_write_header.
|
|
* Preconditions:
|
|
* given wav handle is a valid one obtained as return value of
|
|
* wav_open/wav_fdopen.
|
|
* Postconditions:
|
|
* N/A
|
|
*/
|
|
int wav_close(WAV handle);
|
|
|
|
/*
|
|
* wav_read_data:
|
|
* read a buffer of pcm data from given wav file. Delivers data
|
|
* in wav-native-byte-order (little endian).
|
|
* This function doesn't mess with given data, it just reads
|
|
* data verbatim from wav file. so caller must take care to
|
|
* split/join channel data or do any needed operation.
|
|
*
|
|
* Parameters:
|
|
* handle: wav handle to write data in
|
|
* buffer: pointer to data to store the data readed
|
|
* bufsize: size of given buffer.
|
|
* Return Value:
|
|
* return of bytes effectively readed from wav file.
|
|
* -1 means an error.
|
|
* Side effects:
|
|
* N/A
|
|
* Preconditions:
|
|
* given wav handle is a valid one obtained as return value of
|
|
* wav_open/wav_fdopen; wav handle was opened in WAV_READ mode.
|
|
* bufsize is a multiple of 2.
|
|
* Postconditions:
|
|
* N/A
|
|
*/
|
|
ssize_t wav_read_data(WAV handle, uint8_t *buffer, size_t bufsize);
|
|
|
|
/*
|
|
* wav_write_data:
|
|
* write a buffer of pcm data in given wav file. Expect data
|
|
* in wav-native-byte-order (little endian).
|
|
* This function doesn't mess with given data, it just writes
|
|
* data verbatim on wav file. so caller must take care to
|
|
* split/join channel data or do any needed operation.
|
|
*
|
|
* Parameters:
|
|
* handle: wav handle to write data in
|
|
* buffer: pointer to data to be written
|
|
* bufsize: number of bytes of data to write
|
|
* Return Value:
|
|
* return of bytes effectively written on wav file.
|
|
* -1 means an error.
|
|
* Side effects:
|
|
* N/A
|
|
* Preconditions:
|
|
* given wav handle is a valid one obtained as return value of
|
|
* wav_open/wav_fdopen; wav handle was opened in WAV_WRITE mode.
|
|
* buffer contains data in wav-native-byte-order (little endian)
|
|
* bufsize is a multiple of 2.
|
|
* Postconditions:
|
|
* N/A
|
|
*/
|
|
ssize_t wav_write_data(WAV handle, const uint8_t *buffer, size_t bufsize);
|
|
|
|
/*
|
|
* wav_chunk_size:
|
|
* guess^Wcompute the appropriate buffer size for reading/writing data
|
|
* with given wav descriptor.
|
|
*
|
|
* Parameters:
|
|
* handle: wav descriptor to work on
|
|
* Return Value:
|
|
* suggested size of buffer for R/W operations
|
|
* Side effects:
|
|
* N/A
|
|
* Preconditions:
|
|
* Of course given wav handle is must be a valid one obtained as return
|
|
* value of wav_open/wav_fdopen; additionally, wav header for given
|
|
* descriptor must be fully avalaible.
|
|
* This is always true if wav file was opened in read mode. If wav file
|
|
* was opened in write mode, caller must ensure to issue all stream
|
|
* parameters using wav_set_<someting> (and possibly to use
|
|
* wav_write_header) BEFORE to use this function.
|
|
* Otherwise, caller will get an unreliable result (aka: garbage).
|
|
* Postconditions:
|
|
* N/A
|
|
*/
|
|
uint32_t wav_chunk_size(WAV handle, double fps);
|
|
|
|
/*
|
|
* wav_last_error:
|
|
* get descriptor of last error related to given wav descriptor.
|
|
*
|
|
* Parameters:
|
|
* handle: a wav descriptor.
|
|
* Return Value:
|
|
* code of last error occurred.
|
|
* Side effects:
|
|
* N/A
|
|
* Preconditions:
|
|
* given wav descriptor was obtained as valid return value of
|
|
* wav_open/wav_fdopen.
|
|
* Postconditions:
|
|
* N/A
|
|
*/
|
|
WAVError wav_last_error(WAV handle);
|
|
|
|
/*
|
|
* wav_strerror:
|
|
* get a human-readable short description of an error code
|
|
*
|
|
* Parameters:
|
|
* err: error code to describe
|
|
* Return Value:
|
|
* a pointer to a C-string describing the given error code,
|
|
* or NULL if given error code isn't known.
|
|
* Side effects:
|
|
* N/A
|
|
* Preconditions:
|
|
* N/A
|
|
* Postconditions:
|
|
* N/A
|
|
*/
|
|
const char *wav_strerror(WAVError err);
|
|
|
|
/*
|
|
* wav_write_header:
|
|
* update header for WAVE file using information stored
|
|
* in attached WAV descriptor.
|
|
* This function MAKE NO SENSE if applied to a WAV
|
|
* descriptor open in WAV_READ mode.
|
|
*
|
|
* IMPORTANT NOTICE:
|
|
* If wav_write_header is applied to a WAV descriptor
|
|
* using WAV_WRITE|WAV_PIPE mode, *it doesn't seek at all*,
|
|
* so it will simply write the full WAVE header into
|
|
* stream at current position.
|
|
* This actually is a *design decision*, the intended usage
|
|
* of this function when dealing with WAV_WRITE|WAV_PIPE
|
|
* descriptor is something like this:
|
|
*
|
|
* WAV wav = wav_fdopen(my_fd, WAV_WRITE|WAV_PIPE, NULL);
|
|
*
|
|
* <set WAVE parameters using multiple wav_set_*>
|
|
*
|
|
* wav_write_header(wav, 1);
|
|
*
|
|
* while (1) {
|
|
* bytes = get_data(buffer, bufsize);
|
|
* if(no_more_data()) {
|
|
* break;
|
|
* }
|
|
* if (wav_write_data(wav, buffer, bytes) != 0) {
|
|
* break;
|
|
* }
|
|
* }
|
|
*
|
|
* Parameters:
|
|
* handle: update header for WAVE file attached to this
|
|
* descriptor
|
|
* force: if !0, update header even if isn't needed
|
|
* Return Value:
|
|
* 0 successfull, -1 otherwise
|
|
* Side effects:
|
|
* WAVE header is (re)written on file. This usually
|
|
* requires some seeks on file.
|
|
* See above if WAV_PIPE mode is used
|
|
* Preconditions:
|
|
* given wav descriptor is a valid one obtained as return value of
|
|
* wav_open or wav_fdopen.
|
|
* Postconditions:
|
|
* N/A
|
|
*/
|
|
int wav_write_header(WAV handle, int force);
|
|
|
|
|
|
/*
|
|
* wav_{get,set}_*:
|
|
* set or get interesting WAV parameters.
|
|
* wav_get_* functions can always be used if WAV descriptor is both
|
|
* in read or write mode, but wav_set_* functions hare honoured
|
|
* only if wav descriptor is in write mode.
|
|
* wav_set_* functions applied to a read-mode wav are silently
|
|
* discarderd.
|
|
*
|
|
* avalaible parameters:
|
|
* rate (Average Samples Per Second): quantization rate of stream, Hz.
|
|
* channels: number of channels in stream.
|
|
* bits: size in bits for every sample.
|
|
* bitrate (derived from Average Bytes per Second):
|
|
* bytes needed to store a second of data.
|
|
* Expressed in *KILOBIT/second*.
|
|
*
|
|
* Parameters:
|
|
* handle: handle to a WAV descriptor returned by wav_open/wav_fdopen.
|
|
* <parameter>: (only wav_set_*) value of parameter to set in descriptor.
|
|
* Return Value:
|
|
* wav_get_*: value of requested parameter.
|
|
* wav_set_*: None.
|
|
* Side effects:
|
|
* N/A
|
|
* Preconditions:
|
|
* given wav descriptor is a valid one obtained as return value of
|
|
* wav_open or wav_fdopen.
|
|
* Postconditions:
|
|
* N/A
|
|
*/
|
|
|
|
uint16_t wav_get_rate(WAV handle);
|
|
void wav_set_rate(WAV handle, uint16_t rate);
|
|
|
|
uint8_t wav_get_channels(WAV handle);
|
|
void wav_set_channels(WAV handle, uint8_t channels);
|
|
|
|
uint8_t wav_get_bits(WAV handle);
|
|
void wav_set_bits(WAV handle, uint8_t bits);
|
|
|
|
uint32_t wav_get_bitrate(WAV handle);
|
|
void wav_set_bitrate(WAV handle, uint32_t bitrate);
|
|
|
|
#endif /* _WAVLIB_H_ */
|