Basic sound file manipulation

API for opening, closing and flushing sound files. More...

Modules
	Virtual I/O
	SndFile2K calls the callbacks provided by the SF_VIRTUAL_IO structure when opening, reading and writing to the virtual file context.

Typedefs
typedef struct sf_private_tag	SNDFILE
	Represents opened sound file. More...
typedef sf_count_t(*	sf_vio_tell) (void *user_data)
	Type of user defined function that returns current position in file. More...

Enumerations
enum	SF_FILEMODE { SFM_READ = 0x10, SFM_WRITE = 0x20, SFM_RDWR = 0x30 }
	Defines the kind of file access. More...
enum	SF_SEEK_MODE { SF_SEEK_SET = SEEK_SET, SF_SEEK_CUR = SEEK_CUR, SF_SEEK_END = SEEK_END }
	Defines file seek mode constants. More...

Functions
SNDFILE2K_EXPORT SNDFILE *	sf_open (const char *path, int mode, SF_INFO *sfinfo)
	Opens the specified sound file using path. More...
SNDFILE2K_EXPORT SNDFILE *	sf_open_fd (int fd, int mode, SF_INFO *sfinfo, int close_desc)
	Opens sound file using POSIX file descriptor. More...
SNDFILE2K_EXPORT sf_count_t	sf_seek (SNDFILE *sndfile, sf_count_t frames, int whence)
	Changes position of sound file. More...
SNDFILE2K_EXPORT void	sf_write_sync (SNDFILE *sndfile)
	Forces writing of data to disk. More...

Detailed Description

API for opening, closing and flushing sound files.

Typedef Documentation

sf_vio_tell

typedef sf_count_t(* sf_vio_tell) (void *user_data)

Type of user defined function that returns current position in file.

Parameters

[in]

user_data

User defined value.

Returns

File offset on success, -1 otherwise.

SNDFILE

typedef struct sf_private_tag SNDFILE

Represents opened sound file.

Pointer to SNDFILE is returned by set of file open finctions, including sf_open(), sf_open_fd() and sf_open_virtual(). Most of API functions take SNDFILE pointer as required parameter.

Make no assumptions about SNDFILE internal structure, it is subject to change in future releases.

Any created SNDFILE should be destroyed by sf_close() function to avoid memory leaks.

Enumeration Type Documentation

SF_FILEMODE

enum SF_FILEMODE

Defines the kind of file access.

Enumerator
SFM_READ	Read mode.
SFM_WRITE	Write mode.
SFM_RDWR	Read/write mode.

SF_SEEK_MODE

enum SF_SEEK_MODE

Defines file seek mode constants.

Enumerator
SF_SEEK_SET	Seek from beginning.
SF_SEEK_CUR	Seek from current position.
SF_SEEK_END	Seek from end.

Function Documentation

sf_open()

SNDFILE2K_EXPORT SNDFILE* sf_open	(	const char *	path,
		int	mode,
		SF_INFO *	sfinfo
	)

Opens the specified sound file using path.

Parameters

[in]	path	Path to the file
[in]	mode	File open mode
[in,out]	sfinfo	Format information

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 sf_wchar_open() that takes a UTF16_BE encoded filename.

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

When opening a file for read, the SF_INFO::format field should be set to zero before passing to sf_open(). The only exception to this is the case of RAW files where the caller has to set the samplerate, channels and format fields to valid values. All other fields of the structure are filled in by the library.

When opening a file for write, the caller must fill in structure members SF_INFO::samplerate, SF_INFO::channels, and SF_INFO::format.

All calls to sf_open() should be matched with a call to sf_close().

Returns

A valid pointer to a SNDFILE object on success, NULL otherwise.

See also

sf_wchar_open(), sf_open_fd(), sf_open_virtual()

sf_close()

sf_open_fd()

SNDFILE2K_EXPORT SNDFILE* sf_open_fd	(	int	fd,
		int	mode,
		SF_INFO *	sfinfo,
		int	close_desc
	)

Opens sound file using POSIX file descriptor.

Parameters

[in]	fd	File descriptor
[in]	mode	File open mode
[in,out]	sfinfo	Format information
[in]	close_desc	File descriptor close mode

sf_open_fd() is similar to sf_open(), 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 sf_close() is called, the file descriptor is only closed if the close_desc parameter was SF_TRUE when the sf_open_fd() function was called.

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.

Returns

A valid pointer to a SNDFILE object on success, NULL otherwise.

Deprecated:

This function and will be removed in next major release. Use sf_open_virtual_ex() function instead.

See also

sf_open(), sf_wchar_open(), sf_open_virtual()

sf_close()

sf_seek()

SNDFILE2K_EXPORT sf_count_t sf_seek	(	SNDFILE *	sndfile,
		sf_count_t	frames,
		int	whence
	)

Changes position of sound file.

Parameters

[in]	sndfile	Pointer to a sound file state
[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).

sf_write_sync()

SNDFILE2K_EXPORT void sf_write_sync

(

SNDFILE *

sndfile

)

Forces writing of data to disk.

Parameters

[in]

sndfile

Pointer to a sound file state

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.