-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Haskell bindings for libsndfile -- -- Haskell bindings for libsndfile, a comprehensive C library for -- reading and writing a large number of soundfile formats by Erik de -- Castro Lopo (http://www.mega-nerd.com/libsndfile/). -- -- For more information on hsndfile visit its homepage at -- http://haskell.org/haskellwiki/Hsndfile. @package hsndfile @version 0.5.2 -- | This module provides the Buffer type class that abstracts the -- array type that is being used for I/O. For concrete instances see for -- example the hsndfile-vector package -- http://hackage.haskell.org/package/hsndfile-vector. module Sound.File.Sndfile.Buffer -- | The class Sample is used for polymorphic I/O on a Handle, and -- is parameterized with the element type that is to be read from a file. -- -- 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 -- currently supports reading and writing Double or Float -- floating point values, as well as Word16 and Word32 -- integer values. -- -- When converting between integer data and floating point data, the -- following rules apply: The default behaviour when reading floating -- point data 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 (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. class Storable e => Sample e hGetBuf :: Sample e => Handle -> Ptr e -> Count -> IO Count hPutBuf :: Sample e => Handle -> Ptr e -> Count -> IO Count -- | Buffer class for I/O on soundfile handles. class Buffer a e fromForeignPtr :: Buffer a e => ForeignPtr e -> Int -> Int -> IO (a e) toForeignPtr :: Buffer a e => a e -> IO (ForeignPtr e, Int, Int) -- | Return an buffer with the requested number of frames of data. -- -- The resulting buffer size is equal to the product of the number of -- frames n and the number of channels in the soundfile. hGetBuffer :: (Sample e, Storable e, Buffer a e) => Handle -> Count -> IO (Maybe (a e)) -- | Return the contents of a handle open for reading in a single buffer. hGetContents :: (Sample e, Buffer a e) => Handle -> IO (Info, Maybe (a e)) -- | Return the contents of a file in a single buffer. readFile :: (Sample e, Buffer a e) => FilePath -> IO (Info, Maybe (a e)) -- | Write the contents of a buffer to a handle open for writing. -- -- Return the number of frames written. hPutBuffer :: (Sample e, Storable e, Buffer a e) => Handle -> a e -> IO Count -- | Write the contents of a buffer to a file. Return the number of frames -- written. writeFile :: (Sample e, Buffer a e) => Info -> FilePath -> a e -> IO Count -- | Sound.File.Sndfile provides a Haskell interface to the -- libsndfile library by Erik de Castro Lopo (visit the library's website -- at http://www.mega-nerd.com/libsndfile/). The API is modeled -- after the original C API, but type and function identifiers -- follow Haskell naming conventions. module Sound.File.Sndfile -- | Type for expressing sample counts. type Count = Int -- | Type for expressing sample indices. type Index = Int -- | Stream format specification, consisting of header, sample and -- endianness formats. -- -- Not all combinations of header, sample and endianness formats are -- valid; valid combinations can be checked with the checkFormat -- function. data Format Format :: HeaderFormat -> SampleFormat -> EndianFormat -> Format headerFormat :: Format -> HeaderFormat sampleFormat :: Format -> SampleFormat endianFormat :: Format -> EndianFormat -- | Header format. data HeaderFormat HeaderFormatNone :: HeaderFormat HeaderFormatWav :: HeaderFormat HeaderFormatAiff :: HeaderFormat HeaderFormatAu :: HeaderFormat HeaderFormatRaw :: HeaderFormat HeaderFormatPaf :: HeaderFormat HeaderFormatSvx :: HeaderFormat HeaderFormatNist :: HeaderFormat HeaderFormatVoc :: HeaderFormat HeaderFormatIrcam :: HeaderFormat HeaderFormatW64 :: HeaderFormat HeaderFormatMat4 :: HeaderFormat HeaderFormatMat5 :: HeaderFormat HeaderFormatPvf :: HeaderFormat HeaderFormatXi :: HeaderFormat HeaderFormatHtk :: HeaderFormat HeaderFormatSds :: HeaderFormat HeaderFormatAvr :: HeaderFormat HeaderFormatWavex :: HeaderFormat HeaderFormatSd2 :: HeaderFormat HeaderFormatFlac :: HeaderFormat HeaderFormatCaf :: HeaderFormat -- | Sample format. data SampleFormat SampleFormatNone :: SampleFormat SampleFormatPcmS8 :: SampleFormat SampleFormatPcm16 :: SampleFormat SampleFormatPcm24 :: SampleFormat SampleFormatPcm32 :: SampleFormat SampleFormatPcmU8 :: SampleFormat SampleFormatFloat :: SampleFormat SampleFormatDouble :: SampleFormat SampleFormatUlaw :: SampleFormat SampleFormatAlaw :: SampleFormat SampleFormatImaAdpcm :: SampleFormat SampleFormatMsAdpcm :: SampleFormat SampleFormatGsm610 :: SampleFormat SampleFormatVoxAdpcm :: SampleFormat SampleFormatG72132 :: SampleFormat SampleFormatG72324 :: SampleFormat SampleFormatG72340 :: SampleFormat SampleFormatDwvw12 :: SampleFormat SampleFormatDwvw16 :: SampleFormat SampleFormatDwvw24 :: SampleFormat SampleFormatDwvwN :: SampleFormat SampleFormatFormatDpcm8 :: SampleFormat SampleFormatFormatDpcm16 :: SampleFormat -- | Endianness. data EndianFormat EndianFile :: EndianFormat EndianLittle :: EndianFormat EndianBig :: EndianFormat EndianCpu :: EndianFormat -- | Default 'empty' format, useful when opening files for reading with -- ReadMode. defaultFormat :: Format -- | The Info structure is for passing data between the calling -- function and the library when opening a stream for reading or writing. data Info Info :: Count -> Int -> Int -> Format -> Int -> Bool -> Info -- | Number of frames in file frames :: Info -> Count -- | Audio sample rate samplerate :: Info -> Int -- | Number of channels channels :: Info -> Int -- | Header and sample format format :: Info -> Format -- | Number of sections sections :: Info -> Int -- | True when stream is seekable (e.g. local files) seekable :: Info -> Bool -- | Return soundfile duration in seconds computed via the Info -- fields frames and samplerate. duration :: Info -> Double -- | Default 'empty' info, useful when opening files for reading with -- ReadMode. defaultInfo :: Info -- | 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. checkFormat :: Info -> Bool -- | Abstract file handle. data Handle -- | Return the stream Info associated with the Handle. hInfo :: Handle -> Info hIsSeekable :: Handle -> IO Bool -- | I/O mode. data IOMode ReadMode :: IOMode WriteMode :: IOMode ReadWriteMode :: IOMode openFile :: FilePath -> IOMode -> Info -> IO Handle -- | Get header format information associated with file. getFileInfo :: FilePath -> IO Info -- | 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. hFlush :: Handle -> IO () -- | The hClose function closes the stream, deallocates its internal -- buffers and returns () on success or signals an Exception -- otherwise. hClose :: Handle -> IO () data SeekMode AbsoluteSeek :: SeekMode RelativeSeek :: SeekMode SeekFromEnd :: SeekMode -- | 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: -- -- -- -- 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. hSeek :: Handle -> SeekMode -> Count -> IO Count -- | Like hSeek, but only the read pointer is modified. hSeekRead :: Handle -> SeekMode -> Count -> IO Count -- | Like hSeek, but only the write pointer is modified. hSeekWrite :: Handle -> SeekMode -> Count -> IO Count -- | The class Sample is used for polymorphic I/O on a Handle, and -- is parameterized with the element type that is to be read from a file. -- -- 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 -- currently supports reading and writing Double or Float -- floating point values, as well as Word16 and Word32 -- integer values. -- -- When converting between integer data and floating point data, the -- following rules apply: The default behaviour when reading floating -- point data 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 (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. class Storable e => Sample e hGetBuf :: Sample e => Handle -> Ptr e -> Count -> IO Count hPutBuf :: Sample e => Handle -> Ptr e -> Count -> IO Count -- | Buffer class for I/O on soundfile handles. class Buffer a e fromForeignPtr :: Buffer a e => ForeignPtr e -> Int -> Int -> IO (a e) toForeignPtr :: Buffer a e => a e -> IO (ForeignPtr e, Int, Int) -- | Return an buffer with the requested number of frames of data. -- -- The resulting buffer size is equal to the product of the number of -- frames n and the number of channels in the soundfile. hGetBuffer :: (Sample e, Storable e, Buffer a e) => Handle -> Count -> IO (Maybe (a e)) -- | Return the contents of a handle open for reading in a single buffer. hGetContents :: (Sample e, Buffer a e) => Handle -> IO (Info, Maybe (a e)) -- | Return the contents of a file in a single buffer. readFile :: (Sample e, Buffer a e) => FilePath -> IO (Info, Maybe (a e)) -- | Write the contents of a buffer to a handle open for writing. -- -- Return the number of frames written. hPutBuffer :: (Sample e, Storable e, Buffer a e) => Handle -> a e -> IO Count -- | Write the contents of a buffer to a file. Return the number of frames -- written. writeFile :: (Sample e, Buffer a e) => Info -> FilePath -> a e -> IO Count -- | Values of type Exception are thrown by the library when an -- error occurs. -- -- Use catch to catch only exceptions of this type. data Exception Exception :: String -> Exception errorString :: Exception -> String UnrecognisedFormat :: String -> Exception errorString :: Exception -> String SystemError :: String -> Exception errorString :: Exception -> String MalformedFile :: String -> Exception errorString :: Exception -> String UnsupportedEncoding :: String -> Exception errorString :: Exception -> String -- | This is the simplest of the exception-catching functions. It takes a -- single argument, runs it, and if an exception is raised the "handler" -- is executed, with the value of the exception passed as an argument. -- Otherwise, the result is returned as normal. For example: -- -- 
--   catch (readFile f)
--         (\e -> do let err = show (e :: IOException)
--                   hPutStr stderr ("Warning: Couldn't open " ++ f ++ ": " ++ err)
--                   return "")
--
-- -- Note that we have to give a type signature to e, or the -- program will not typecheck as the type is ambiguous. While it is -- possible to catch exceptions of any type, see the previous section -- "Catching all exceptions" for an explanation of the problems with -- doing so. -- -- For catching exceptions in pure (non-IO) expressions, see the -- function evaluate. -- -- Note that due to Haskell's unspecified evaluation order, an expression -- may throw one of several possible exceptions: consider the expression -- (error "urk") + (1 `div` 0). Does the expression throw -- ErrorCall "urk", or DivideByZero? -- -- The answer is "it might throw either"; the choice is -- non-deterministic. If you are catching any type of exception then you -- might catch either. If you are calling catch with type IO -- Int -> (ArithException -> IO Int) -> IO Int then the -- handler may get run with DivideByZero as an argument, or an -- ErrorCall "urk" exception may be propogated further up. If -- you call it again, you might get a the opposite behaviour. This is ok, -- because catch is an IO computation. -- -- Note that the Prelude also exports a function called -- Prelude.catch with a similar type to -- Control.Exception.catch, except that the Prelude -- version only catches the IO and user families of exceptions (as -- required by Haskell 98). -- -- We recommend either hiding the Prelude version of -- Prelude.catch when importing Control.Exception: -- -- 
--   import Prelude hiding (catch)
--
-- -- or importing Control.Exception qualified, to avoid -- name-clashes: -- -- 
--   import qualified Control.Exception as C
--
-- -- and then using C.catch catch :: Exception e => IO a -> (e -> IO a) -> IO a -- | Header string field types. data StringType StrTitle :: StringType StrCopyright :: StringType StrSoftware :: StringType StrArtist :: StringType StrComment :: StringType StrDate :: StringType -- | The getString function returns the specified string from the -- stream header in the Maybe monad if it exists and -- Nothing otherwise. getString :: Handle -> StringType -> IO (Maybe String) -- | The setString function sets the string data associated with the -- respective StringType. setString :: Handle -> StringType -> String -> IO ()