SndFile class. More...

#include <sndfile2k/sndfile2k.hpp>

Public Member Functions
	SndfileHandle (void)
	SndFileHandle default constructor.

	SndfileHandle (const char *path, int mode=SFM_READ, int format=0, int channels=0, int samplerate=0)
	Opens the specified file using path. More...

	SndfileHandle (std::string const &path, int mode=SFM_READ, int format=0, int channels=0, int samplerate=0)
	Opens the specified file using path. More...

	SndfileHandle (int fd, bool close_desc, int mode=SFM_READ, int format=0, int channels=0, int samplerate=0)
	Opens file using `POSIX` file descriptor. More...

	SndfileHandle (SF_VIRTUAL_IO &sfvirtual, void *user_data, int mode=SFM_READ, int format=0, int channels=0, int samplerate=0)
	Opens sound file using Virtual I/O context. More...

	~SndfileHandle (void)
	SndfileHandle destructor.

	SndfileHandle (const SndfileHandle &orig)
	SndfileHandle copy constructor.

SndfileHandle &	operator= (const SndfileHandle &rhs)
	Assignment operator.

int	refCount (void) const
	Gets number of references to this sound file.

	operator bool () const
	Compares sound file with NULL.

bool	operator== (const SndfileHandle &rhs) const
	Compares one sound file object with other.

sf_count_t	frames (void) const
	Gets number of frames.

int	format (void) const
	Gets format. More...

int	channels (void) const
	Gets number of channels.

int	samplerate (void) const
	Gets samplerate.

int	error (void) const
	Gets the current error code of sound file object. More...

const char *	strError (void) const
	Returns textual description of the current error code. More...

int	command (int cmd, void *data, int datasize)
	Gets or sets parameters of library or sound file object. More...

sf_count_t	seek (sf_count_t frames, int whence)
	Changes position of sound file. More...

void	writeSync (void)
	Forces writing of data to disk. More...

int	setString (int str_type, const char *str)
	Sets string field. More...

const char *	getString (int str_type) const
	Gets string field. More...

sf_count_t	read (short *ptr, sf_count_t items)
	Reads short (16-bit) samples from file. More...

sf_count_t	read (int *ptr, sf_count_t items)
	Reads integer (32-bit) samples from file. More...

sf_count_t	read (float *ptr, sf_count_t items)
	Reads float (32-bit) samples from file. More...

sf_count_t	read (double *ptr, sf_count_t items)
	Reads double (64-bit) samples from file. More...

sf_count_t	write (const short *ptr, sf_count_t items)
	Writes short (16-bit) samples to file. More...

sf_count_t	write (const int *ptr, sf_count_t items)
	Writes integer (32-bit) samples to file. More...

sf_count_t	write (const float *ptr, sf_count_t items)
	Writes float (32-bit) samples to file. More...

sf_count_t	write (const double *ptr, sf_count_t items)
	Writes double (64-bit) samples to file. More...

sf_count_t	readf (short *ptr, sf_count_t frames)
	Reads short (16-bit) frames from file. More...

sf_count_t	readf (int *ptr, sf_count_t frames)
	Reads integer (32-bit) frames from file. More...

sf_count_t	readf (float *ptr, sf_count_t frames)
	Reads float (32-bit) frames from file. More...

sf_count_t	readf (double *ptr, sf_count_t frames)
	Reads double (64-bit) frames from file. More...

sf_count_t	writef (const short *ptr, sf_count_t frames)
	Writes short (16-bit) frames to file. More...

sf_count_t	writef (const int *ptr, sf_count_t frames)
	Writes integer (32-bit) frames to file. More...

sf_count_t	writef (const float *ptr, sf_count_t frames)
	Writes float (32-bit) frames to file. More...

sf_count_t	writef (const double *ptr, sf_count_t frames)
	Writes double (64-bit) frames to file. More...

sf_count_t	readRaw (void *ptr, sf_count_t bytes)
	Read raw bytes from sound file. More...

sf_count_t	writeRaw (const void *ptr, sf_count_t bytes)
	Writes raw bytes to sound file. More...

SNDFILE *	rawHandle (void)
	Gets ccess to the raw sound file handle.

SNDFILE *	takeOwnership (void)
	Takes ownership of handle, if reference count is 1.

Static Public Member Functions
static int	formatCheck (int format, int channels, int samplerate)
	Checks correctness of format parameters combination. More...

Detailed Description

SndFile class.

Constructor & Destructor Documentation

◆ SndfileHandle() [1/4]

SndfileHandle::SndfileHandle	(	const char *	path,
		int	mode = `SFM_READ`,
		int	format = `0`,
		int	channels = `0`,
		int	samplerate = `0`
	)

inline

Opens the specified file using path.

Parameters

[in]	path	Path to the file
[in]	mode	File open mode
[in]	format	Format
[in]	channels	Number of channels
[in]	samplerate	Samplerate

The path is byte encoded, but may be utf-8 on Linux, while on Mac OS X it will use the filesystem character set. On Windows, there is also a Windows specific SndfileHandle(const wchar_t *, int, int, int) that takes a UTF16_BE encoded filename.

The mode specifies the kind of access that is requested for the file, one of SF_FILEMODE values.

When opening a file for read, the format field should be set to zero before passing to constructor. The only exception to this is the case of RAW files where the caller has to set the samplerate, channels and format parameters to valid values.

When opening a file for write, the caller must fill samplerate, channels, format.

See also: sf_wchar_open(), sf_open_fd(), sf_open_virtual(); sf_close()

◆ SndfileHandle() [2/4]

SndfileHandle::SndfileHandle	(	std::string const &	path,
		int	mode = `SFM_READ`,
		int	format = `0`,
		int	channels = `0`,
		int	samplerate = `0`
	)

inline

Opens the specified file using path.

Parameters

[in]	path	Path to the file
[in]	mode	File open mode
[in]	format	Format
[in]	channels	Number of channels
[in]	samplerate	Samplerate

This constructor is similar to SndfileHandle(const char *, int, int, int), but takes std::string as path.

See also: sf_wchar_open(), sf_open_fd(), sf_open_virtual(); sf_close()

◆ SndfileHandle() [3/4]

SndfileHandle::SndfileHandle	(	int	fd,
		bool	close_desc,
		int	mode = `SFM_READ`,
		int	format = `0`,
		int	channels = `0`,
		int	samplerate = `0`
	)

inline

Opens file using POSIX file descriptor.

Parameters

[in]	fd	File descriptor
[in]	close_desc	File descriptor close mode
[in]	mode	File open mode
[in]	format	Format
[in]	channels	Number of channels
[in]	samplerate	Samplerate

This constructor is similar to SndfileHandle(const char *, int, int, int), but takes POSIX file descriptor of already opened file instead of path.

Care should be taken to ensure that the mode of the file represented by the descriptor matches the mode argument.

This function is useful in the following circumstances:

Opening temporary files securely (ie use the tmpfile() to return a FILE* pointer and then using fileno() to retrieve the file descriptor which is then passed to sndfile2k.
Opening files with file names using OS specific character encodings and then passing the file descriptor to sf_open_fd().
Opening sound files embedded within larger files.

When destructor is called, the file descriptor is only closed if the close_desc parameter is set SF_TRUE.

Note: On Microsoft Windows, this function does not work if the application and the sndfile2k DLL are linked to different versions of the Microsoft C runtime DLL.

See also: sf_open(), sf_wchar_open(), sf_open_virtual(); sf_close()

◆ SndfileHandle() [4/4]

SndfileHandle::SndfileHandle	(	SF_VIRTUAL_IO &	sfvirtual,
		void *	user_data,
		int	mode = `SFM_READ`,
		int	format = `0`,
		int	channels = `0`,
		int	samplerate = `0`
	)

inline

Opens sound file using Virtual I/O context.

Parameters

[in]	sfvirtual	Virtual I/O context
[in]	user_data	User data
[in]	mode	File open mode
[in]	format	Format
[in]	channels	Number of channels
[in]	samplerate	Samplerate

This constructor is similar to SndfileHandle(const char *, int, int, int), but takes Virtual I/O context of already opened file instead of path.

Care should be taken to ensure that the mode of the file represented by the descriptor matches the mode argument.

See also: sf_open(), sf_wchar_open(), sf_open_fd(); sf_close()

Member Function Documentation

◆ command()

int SndfileHandle::command	(	int	cmd,
		void *	data,
		int	datasize
	)

inline

Gets or sets parameters of library or sound file object.

Parameters

cmd	Command ID see SF_COMMAND for details
data	Command specific, could be `NULL`
datasize	Size of `data`, could be `0`

Returns: Command-specific, see particular command description.

◆ error()

int SndfileHandle::error ( void ) const

inline

Gets the current error code of sound file object.

The error code may be one of SF_ERR values, or any one of many other internal error values.

Applications should only test the return value against SF_ERR values as the internal error values are subject to change at any time.

For errors not in the above list, the strError() method can be used to convert it to an error string.

Returns: Error number.

See also: strError()

◆ format()

int SndfileHandle::format ( void ) const

inline

Gets format.

See also: SF_FORMAT

◆ formatCheck()

int SndfileHandle::formatCheck	(	int	format,
		int	channels,
		int	samplerate
	)

inlinestatic

Checks correctness of format parameters combination.

To open sound file in write mode you need to set up format, channels and samplerate parameters. To be sure that combination is correct and will be accepted you can use this method.

Returns: SF_TRUE if format is valid, SF_FALSE otherwise.

See also: sf_format_check()

◆ getString()

const char * SndfileHandle::getString ( int str_type ) const

inline

Gets string field.

Parameters

[in] str_type Type of field to retrieve, one of SF_STR_FIELD values.

Returns: Zero-terminated string in utf-8 encoding on success or NULL otherwise.

Parameters

[in] str_type Type of field to retrieve, one of SF_STR_FIELD values

Returns: Zero-terminated string in utf-8 encoding on success or NULL otherwise.

◆ read() [1/4]

sf_count_t SndfileHandle::read	(	short *	ptr,
		sf_count_t	items
	)

inline

Reads short (16-bit) samples from file.

Parameters

[out]	ptr	Pointer to an allocated block of memory.
[in]	items	Count of samples to read

Returns: Number of samples actually read.

◆ read() [2/4]

sf_count_t SndfileHandle::read	(	int *	ptr,
		sf_count_t	items
	)

inline

Reads integer (32-bit) samples from file.

Parameters

[out]	ptr	Pointer to an allocated block of memory.
[in]	items	Count of samples to read

Returns: Number of samples actually read.

◆ read() [3/4]

sf_count_t SndfileHandle::read	(	float *	ptr,
		sf_count_t	items
	)

inline

Reads float (32-bit) samples from file.

Parameters

[out]	ptr	Pointer to an allocated block of memory.
[in]	items	Count of samples to read

Returns: Number of samples actually read.

◆ read() [4/4]

sf_count_t SndfileHandle::read	(	double *	ptr,
		sf_count_t	items
	)

inline

Reads double (64-bit) samples from file.

Parameters

[out]	ptr	Pointer to an allocated block of memory.
[in]	items	Count of samples to read

Returns: Number of samples actually read.

◆ readf() [1/4]

sf_count_t SndfileHandle::readf	(	short *	ptr,
		sf_count_t	frames
	)

inline

Reads short (16-bit) frames from file.

Parameters

[out]	ptr	Pointer to an allocated block of memory.
[in]	frames	Count of frames to read

Returns: Number of frames actually read.

◆ readf() [2/4]

sf_count_t SndfileHandle::readf	(	int *	ptr,
		sf_count_t	frames
	)

inline

Reads integer (32-bit) frames from file.

Parameters

[out]	ptr	Pointer to an allocated block of memory.
[in]	frames	Count of frames to read

Returns: Number of frames actually read.

◆ readf() [3/4]

sf_count_t SndfileHandle::readf	(	float *	ptr,
		sf_count_t	frames
	)

inline

Reads float (32-bit) frames from file.

Parameters

[out]	ptr	Pointer to an allocated block of memory.
[in]	frames	Count of frames to read

Returns: Number of frames actually read.

◆ readf() [4/4]

sf_count_t SndfileHandle::readf	(	double *	ptr,
		sf_count_t	frames
	)

inline

Reads double (64-bit) frames from file.

Parameters

[out]	ptr	Pointer to an allocated block of memory.
[in]	frames	Count of frames to read

Returns: Number of frames actually read.

◆ readRaw()

sf_count_t SndfileHandle::readRaw	(	void *	ptr,
		sf_count_t	bytes
	)

inline

Read raw bytes from sound file.

Parameters

[out]	ptr	Pointer to an allocated block memory.
[in]	bytes	Count of bytes to read

Note: This function is not for general use. No type conversion or byte-swapping performed, data is returned as it is.

Returns: Number of bytes actually read.

◆ seek()

sf_count_t SndfileHandle::seek	(	sf_count_t	frames,
		int	whence
	)

inline

Changes position of sound file.

Parameters

[in]	frames	Count of frames
[in]	whence	Seek origin

The file seek functions work much like lseek in unistd.h with the exception that the non-audio data is ignored and the seek only moves within the audio data section of the file. In addition, seeks are defined in number of (multichannel) frames. Therefore, a seek in a stereo file from the current position forward with an offset of 1 would skip forward by one sample of both channels.

Internally, library keeps track of the read and write locations using separate read and write pointers. If a file has been opened with a mode of SFM_RDWR, bitwise OR-ing the standard whence values above with either SFM_READ or SFM_WRITE allows the read and write pointers to be modified separately. If the SEEK_* values are used on their own, the read and write pointers are both modified.

Note: The frames offset can be negative and in fact should be when SF_SEEK_END is used for the whence parameter.

Returns: Offset in (multichannel) frames from the start of the audio data or -1 if an error occured (ie an attempt is made to seek beyond the start or end of the file).

◆ setString()

int SndfileHandle::setString	(	int	str_type,
		const char *	str
	)

inline

Sets string field.

Parameters

[in]	str_type	Type of field to set, one of SF_STR_FIELD values
[in]	str	Pointer to a null-terminated string with data to set

Note: Strings passed to this function is assumed to be utf-8. However, while formats like Ogg/Vorbis and FLAC fully support utf-8, others like WAV and AIFF officially only support ASCII. Current policy is to write such string as it is without conversion. Such tags can be read back with SndFile2K without problems, but other programs may fail to decode and display data correctly. If you want to write strings in ASCII, perform reencoding before passing data to sf_set_string().

Returns: Zero on success and non-zero value otherwise.

Parameters

[in]	str_type	Type of field to set, one of SF_STR_FIELD values
[in]	str	Pointer to a null-terminated string with data to set

Note: Strings passed to this function is assumed to be utf-8. However, while formats like Ogg/Vorbis and FLAC fully support utf-8, others like WAV and AIFF officially only support ASCII. Current policy is to write such string as it is without conversion. Such tags can be read back with SndFile2K without problems, but other programs may fail to decode and display data correctly. If you want to write strings in ASCII, perform reencoding before passing data to setString().

Returns: Zero on success and non-zero value otherwise.

◆ strError()

const char * SndfileHandle::strError ( void ) const

inline

Returns textual description of the current error code.

Returns: Pointer to the NULL-terminated error description string.

See also: error()

◆ write() [1/4]

sf_count_t SndfileHandle::write	(	const short *	ptr,
		sf_count_t	items
	)

inline

Writes short (16-bit) samples to file.

Parameters

[in]	ptr	Pointer to an allocated block of memory.
[in]	items	Count of samples to write

Returns: Number of samples actually written.

◆ write() [2/4]

sf_count_t SndfileHandle::write	(	const int *	ptr,
		sf_count_t	items
	)

inline

Writes integer (32-bit) samples to file.

Parameters

[in]	ptr	Pointer to an allocated block of memory.
[in]	items	Count of samples to write

Returns: Number of samples actually written.

◆ write() [3/4]

sf_count_t SndfileHandle::write	(	const float *	ptr,
		sf_count_t	items
	)

inline

Writes float (32-bit) samples to file.

Parameters

[in]	ptr	Pointer to an allocated block of memory.
[in]	items	Count of samples to write

Returns: Number of samples actually written.

◆ write() [4/4]

sf_count_t SndfileHandle::write	(	const double *	ptr,
		sf_count_t	items
	)

inline

Writes double (64-bit) samples to file.

Parameters

[in]	ptr	Pointer to an allocated block of memory.
[in]	items	Count of samples to write

Returns: Number of samples actually written.

◆ writef() [1/4]

sf_count_t SndfileHandle::writef	(	const short *	ptr,
		sf_count_t	frames
	)

inline

Writes short (16-bit) frames to file.

Parameters

[in]	ptr	Pointer to an allocated block of memory.
[in]	frames	Count of frames to write

Returns: Number of frames actually written.

◆ writef() [2/4]

sf_count_t SndfileHandle::writef	(	const int *	ptr,
		sf_count_t	frames
	)

inline

Writes integer (32-bit) frames to file.

Parameters

[in]	ptr	Pointer to an allocated block of memory.
[in]	frames	Count of frames to write

Returns: Number of frames actually written.

◆ writef() [3/4]

sf_count_t SndfileHandle::writef	(	const float *	ptr,
		sf_count_t	frames
	)

inline

Writes float (32-bit) frames to file.

Parameters

[in]	ptr	Pointer to an allocated block of memory.
[in]	frames	Count of frames to write

Returns: Number of frames actually written.

◆ writef() [4/4]

sf_count_t SndfileHandle::writef	(	const double *	ptr,
		sf_count_t	frames
	)

inline

Writes double (64-bit) frames to file.

Parameters

[in]	ptr	Pointer to an allocated block of memory.
[in]	frames	Count of frames to write

Returns: Number of frames actually written.

◆ writeRaw()

sf_count_t SndfileHandle::writeRaw	(	const void *	ptr,
		sf_count_t	bytes
	)

inline

Writes raw bytes to sound file.

Parameters

[in]	ptr	Pointer to an allocated block of memory.
[in]	bytes	Count of bytes to write

Note: This function is not for general use. No type conversion or byte-swapping performed, data is written as it is.

Returns: Number of bytes actually written.

◆ writeSync()

void SndfileHandle::writeSync ( void )

inline

Forces writing of data to disk.

If the file is opened SFM_WRITE or SFM_RDWR, call fsync() on the file to force the writing of data to disk. If the file is opened SFM_READ no action is taken.

The documentation for this class was generated from the following file:

sndfile2k/sndfile2k.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SndfileHandle() [1/4]

◆ SndfileHandle() [2/4]

◆ SndfileHandle() [3/4]

◆ SndfileHandle() [4/4]

Member Function Documentation

◆ command()

◆ error()

◆ format()

◆ formatCheck()

◆ getString()

◆ read() [1/4]

◆ read() [2/4]

◆ read() [3/4]

◆ read() [4/4]

◆ readf() [1/4]

◆ readf() [2/4]

◆ readf() [3/4]

◆ readf() [4/4]

◆ readRaw()

◆ seek()

◆ setString()

◆ strError()

◆ write() [1/4]

◆ write() [2/4]

◆ write() [3/4]

◆ write() [4/4]

◆ writef() [1/4]

◆ writef() [2/4]

◆ writef() [3/4]

◆ writef() [4/4]

◆ writeRaw()

◆ writeSync()