Sound.File.Sndfile

Sound.File.Sndfile provides a Haskell interface to the ubiquitous libsndfile library by Erik de Castro Lopo (visit the author's website at http://www.mega-nerd.com/libsndfile/).

Types

type Count = Int

Type for expressing sample counts.

type Index = Int

Type for expressing sample indices.

Stream format

data Format

Stream format specification, consisting of header, sample and endianness formats.

Not all combinations of header, sample and endianness formats are valid; valid combinamtions can be checked with the checkFormat function.

Constructors

Format

Fields

headerFormat :: HeaderFormat

sampleFormat :: SampleFormat

endianFormat :: EndianFormat

Instances

Eq Format

Show Format

data HeaderFormat

Header format.

Constructors

HeaderFormatNone

HeaderFormatWav

HeaderFormatAiff

HeaderFormatAu

HeaderFormatRaw

HeaderFormatPaf

HeaderFormatSvx

HeaderFormatNist

HeaderFormatVoc

HeaderFormatIrcam

HeaderFormatW64

HeaderFormatMat4

HeaderFormatMat5

HeaderFormatPvf

HeaderFormatXi

HeaderFormatHtk

HeaderFormatSds

HeaderFormatAvr

HeaderFormatWavex

HeaderFormatSd2

HeaderFormatFlac

HeaderFormatCaf

Instances

Enum HeaderFormat

Eq HeaderFormat

Show HeaderFormat

data SampleFormat

Sample format.

Constructors

SampleFormatNone

SampleFormatPcmS8

SampleFormatPcm16

SampleFormatPcm24

SampleFormatPcm32

SampleFormatPcmU8

SampleFormatFloat

SampleFormatDouble

SampleFormatUlaw

SampleFormatAlaw

SampleFormatImaAdpcm

SampleFormatMsAdpcm

SampleFormatGsm610

SampleFormatVoxAdpcm

SampleFormatG72132

SampleFormatG72324

SampleFormatG72340

SampleFormatDwvw12

SampleFormatDwvw16

SampleFormatDwvw24

SampleFormatDwvwN

SampleFormatFormatDpcm8

SampleFormatFormatDpcm16

Instances

Enum SampleFormat

Eq SampleFormat

Show SampleFormat

data EndianFormat

Endianness.

Constructors

EndianFile

EndianLittle

EndianBig

EndianCpu

Instances

Enum EndianFormat

Eq EndianFormat

Show EndianFormat

defaultFormat :: Format

Default 'empty' format, useful when opening files for reading with ReadMode.

Stream info

data Info

The Info structure is for passing data between the calling function and the library when opening a stream for reading or writing.

Constructors

Info

Fields

frames :: Count

Number of frames in file

samplerate :: Int

Audio sample rate

channels :: Int

Number of channels

format :: Format

Header and sample format

sections :: Int

Number of sections

seekable :: Bool

True when stream is seekable (e.g. local files)

Instances

Eq Info

Show Info

Storable Info

duration :: Info -> Double

Return soundfile duration in seconds computed via the Info fields frames and samplerate.

defaultInfo :: Info

Default 'empty' info, useful when opening files for reading with ReadMode.

checkFormat :: Info -> Bool

This function allows the caller to check if a set of parameters in the Info struct is valid before calling openFile (WriteMode).

checkFormat returns True if the parameters are valid and False otherwise.

Stream handle operations

data Handle

Abstract file handle.

hInfo :: Handle -> Info

Return the stream Info associated with the Handle.

hIsSeekable :: Handle -> IO Bool

data IOMode

I/O mode.

Constructors

ReadMode

WriteMode

ReadWriteMode

Instances

Enum IOMode

When opening a file for read (ReadMode), the format field should be set to defaultFormat before calling openFile. 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 (WriteMode), the caller must fill in the structure members samplerate, channels, and format.

Every call to openFile should be matched with a call to hClose to free up memory allocated during the call to openFile.

On success, the openFile function returns a Handle which should be passed as the first parameter to all subsequent libsndfile calls dealing with that audio stream. On fail, the openFile function signals an Exception.

Eq IOMode

Show IOMode

openFile :: FilePath -> IOMode -> Info -> IO Handle

getFileInfo :: FilePath -> IO Info

Get header format information associated with file.

hFlush :: Handle -> IO ()

If the stream is opened with WriteMode or ReadWriteMode, call the operating system's function to force the writing of all file cache buffers to disk. If the file is opened with ReadMode no action is taken.

hClose :: Handle -> IO ()

The hClose function closes the stream, deallocates its internal buffers and returns () on success or signals an Exception otherwise.

data SeekMode

Constructors

AbsoluteSeek

RelativeSeek

SeekFromEnd

Instances

Enum SeekMode

Eq SeekMode

Show SeekMode

hSeek :: Handle -> SeekMode -> Count -> IO Count

The file seek functions work much like System.IO.hseek 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.

like lseek(), the whence parameter can be any one of the following three values:

• AbsoluteSeek - The offset is set to the start of the audio data plus offset (multichannel) frames.
• RelativeSeek - The offset is set to its current location plus offset (multichannel) frames.
• SeekFromEnd - The offset is set to the end of the data plus offset (multichannel) frames.

Internally, libsndfile keeps track of the read and write locations using separate read and write pointers. If a file has been opened with a mode of ReadWriteMode, calling either hSeekRead or hSeekWrite allows the read and write pointers to be modified separately. hSeek modifies both the read and the write pointer.

Note that the frames offset can be negative and in fact should be when SeekFromEnd is used for the whence parameter.

hSeek will return the offset in (multichannel) frames from the start of the audio data, or signal an error when an attempt is made to seek beyond the start or end of the file.

hSeekRead :: Handle -> SeekMode -> Count -> IO Count

Like hSeek, but only the read pointer is modified.

hSeekWrite :: Handle -> SeekMode -> Count -> IO Count

Like hSeek, but only the write pointer is modified.

I/O functions

class MArray a e m => MBuffer a e m where

The class MBuffer is used for polymorphic I/O on a Handle, and is parameterized on the mutable array type, the element type and the monad results are returned in.

It is important to note that the data type used by the calling program and the data format of the file do not need to be the same. For instance, it is possible to open a 16 bit PCM encoded WAV file and read the data in floating point format. The library seamlessly converts between the two formats on-the-fly; the Haskell interface only supports reading and writing Double or Float values.

When converting between integer data and floating point data, the following rules apply: The default behaviour when reading floating point data (hGetSamples or hGetFrames) from a file with integer data is normalisation. Regardless of whether data in the file is 8, 16, 24 or 32 bit wide, the data will be read as floating point data in the range [-1.0, 1.0]. Similarly, data in the range [-1.0, 1.0] will be written to an integer PCM file so that a data value of 1.0 will be the largest allowable integer for the given bit width. This normalisation can be turned on or off using the command interface [TODO: implementation missing in Haskell].

hGetSamples and hGetFrames return the number of items read. Unless the end of the file was reached during the read, the return value should equal the number of items requested. Attempts to read beyond the end of the file will not result in an error but will cause the read functions to return less than the number of items requested or 0 if already at the end of the file.

Methods

hGetSamples :: Handle -> a Index e -> Count -> m Count

Fill the destination array with the requested number of items. The count parameter must be an integer product of the number of channels or an error will occur.

hGetFrames :: Handle -> a Index e -> Count -> m Count

Fill the destination array with the requested number of frames of data. The array must be large enough to hold the product of frames and the number of channels or an error will occur.

hPutSamples :: Handle -> a Index e -> Count -> m Count

Write count samples from the source array to the stream. The count parameter must be an integer product of the number of channels or an error will occur.

hPutSamples returns the number of items written (which should be the same as the count parameter).

hPutFrames :: Handle -> a Index e -> Count -> m Count

Write count frames from the source array to the stream. The array must be large enough to hold the product of frames and the number of channels or an error will occur.

hPutFrames returns the number of frames written (which should be the same as the count parameter).

Instances

MBuffer StorableArray Double IO

MBuffer StorableArray Float IO

MBuffer IOCArray Double IO

MBuffer IOCArray Float IO

hReadSamples :: (MBuffer a e m, Num e) => Handle -> Count -> m (Maybe (a Index e))

Return an array with the requested number of items. The count parameter must be an integer product of the number of channels or an error will occur.

hReadFrames :: (MBuffer a e m, Num e) => Handle -> Count -> m (Maybe (a Index e))

Return an array with the requested number of frames of data. The resulting array size is equal to the product of the number of frames n and the number of channels in the soundfile.

interact :: MBuffer a e m => (e -> e) -> a Index e -> Handle -> Handle -> m ()

Exception handling

data Exception

Values of type Exception are thrown by the library when an error occurs.

Use catch to catch only exceptions of this type.

Constructors

Exception

Fields

errorString :: String

UnrecognisedFormat

Fields

errorString :: String

SystemError

Fields

errorString :: String

MalformedFile

Fields

errorString :: String

UnsupportedEncoding

Fields

errorString :: String

Instances

Show Exception

Typeable Exception

Exception Exception

catch :: IO a -> (Exception -> IO a) -> IO a

Catch values of type Exception.

Header string field access

data StringType

Header string field types.

Constructors

StrTitle

StrCopyright

StrSoftware

StrArtist

StrComment

StrDate

Instances

Enum StringType

Eq StringType

Show StringType

getString :: Handle -> StringType -> IO (Maybe String)

The getString function returns the specificed string from the stream header in the Maybe monad if it exists and Nothing otherwise.

setString :: Handle -> StringType -> String -> IO ()

The setString function sets the string data associated with the respective StringType.