-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Audio file reading/writing
--   
--   encode and decode soundfiles using lazy ByteStrings. Audio files may
--   be read or written, with classes and data structures to facilitate
--   conversion between different formats. Currently only wave format is
--   supported. Error handling is supported via Control.Monad.ErrorT.
@package HSoundFile
@version 0.2.2


-- | Datatypes and functions useful for all SoundFile datatypes.
module Sound.Base

-- | The samplerate value, in samples per second.
type SampleRate = Integer

-- | The bit depth, or word length, of audio data.
type BitDepth = Integer

-- | A single sample of audio data. Represented normalized to [-1,1]
type SoundData = Double

-- | One frame of audio data, i.e. the sample value for each channel in the
--   data.
type SoundFrame = [SoundData]

-- | A position in a data stream, or a length, in frame values.
type FrameCount = Integer

-- | An audio data stream. This has both the raw audio data (as a list of
--   <a>SoundFrame</a>), and the total length, in frames.
data AudioSig

-- | Basic information about the audio data: number of channels,
--   samplerate, and bit depth.
data SndFileInfo
SndFileInfo :: Int -> SampleRate -> BitDepth -> SndFileInfo
numChannels :: SndFileInfo -> Int
sr :: SndFileInfo -> SampleRate
bitDepth :: SndFileInfo -> BitDepth

-- | The type of the <a>SndFileCls</a> Internal is a special type used for
--   the SndFile class.
data SndFileType
AIFF :: SndFileType
WavePCM :: SndFileType
OtherSoundFile :: String -> SndFileType
Internal :: SndFileType

-- | A generic datatype for SoundFile data.
data SoundFile
SoundFile :: SndFileInfo -> AudioSig -> SoundFile

-- | The basic class datatypes that represent soundfiles should support.
class SndFileCls a
getSfInfo :: (SndFileCls a, Monad m) => a -> AudioMonad m SndFileInfo
getSfType :: (SndFileCls a) => a -> SndFileType
getAudioData :: (SndFileCls a, Monad m) => a -> AudioMonad m AudioSig
fromSndFileCls :: (SndFileCls a, Monad m) => a -> AudioMonad m SoundFile
getAudioLength :: (SndFileCls a, Monad m) => a -> AudioMonad m FrameCount
data AudioError

-- | Audio format information not found in file
NoFormatError :: AudioError

-- | File is not in a recognized file format
UnknownFileTypeError :: AudioError

-- | Specified bit depth is not supported
InvalidBitDepthError :: BitDepth -> [BitDepth] -> AudioError

-- | unspecified error.
OtherError :: String -> AudioError

-- | Monad to support error handling.
type AudioMonad m = ErrorT AudioError m

-- | length of the audio data.
lengthInFrames :: AudioSig -> FrameCount

-- | The audio data.
audioData :: AudioSig -> [SoundFrame]

-- | Convert an interleaved [<a>SoundData</a>] (e.g., [l1, r1, l2, r2,...])
--   to [<a>SoundFrame</a>]
makeFrames :: Int -> [SoundData] -> [SoundFrame]

-- | Interleave a [[<a>SoundData</a>]] to [<a>SoundFrame</a>], e.g.
--   [[l1,l2,l3], [r1,r2,r3]] -&gt; [[l1,r1], [l2,r2], [l3, r3]]
interleave :: [[SoundData]] -> [SoundFrame]
makeAudioSignal :: FrameCount -> [SoundFrame] -> AudioSig
appendASig :: AudioSig -> AudioSig -> AudioSig
concatASig :: [AudioSig] -> AudioSig
instance Eq SndFileType
instance Show SndFileType
instance Eq SndFileInfo
instance Show SndFileInfo
instance Eq AudioSig
instance Show AudioSig
instance Show SoundFile
instance Eq SoundFile
instance SndFileCls SoundFile
instance NFData SndFileInfo
instance Show AudioError
instance Error AudioError


-- | Encode lazy bytestrings to wave format, and decode lazy bytestrings in
--   wave format to a WaveFile datum.
module Sound.Codecs.WaveFile
newtype WaveFile
WaveFile :: [WaveChunk] -> WaveFile

-- | A SubChunk of a Wave file.
data WaveChunk

-- | Format of the audio data.
WaveFormat :: SndFileInfo -> WaveChunk
format :: WaveChunk -> SndFileInfo

-- | The audio data
WaveData :: ByteString -> Integer -> WaveChunk
waveData :: WaveChunk -> ByteString
chunkLength :: WaveChunk -> Integer

-- | Any metadata in the file.
WaveMeta :: ByteString -> Integer -> WaveChunk
metaData :: WaveChunk -> ByteString
chunkLength :: WaveChunk -> Integer

-- | an unknown chunk type
UnknownWaveChunk :: ByteString -> ByteString -> Integer -> WaveChunk
chunkType :: WaveChunk -> ByteString
unparsedData :: WaveChunk -> ByteString
chunkLength :: WaveChunk -> Integer

-- | return a WaveFile from a bytestring (including header)
getWaveFile :: (Monad m) => ByteString -> AudioMonad m (WaveFile)

-- | Create a WaveFile from a SndFileCls
toWaveFile :: (SndFileCls a, Monad m) => a -> AudioMonad m WaveFile

-- | determine (based on header information) if the bytestring is a wave
--   file.
isWaveFile :: ByteString -> Bool
instance Show WaveFile
instance Eq WaveFile
instance Show WaveChunk
instance Eq WaveChunk
instance SndFileCls WaveFile
instance Binary WaveFile
instance Binary WaveChunk


-- | Enable reading and writing of SoundFiles. This module defines several
--   datatypes for multiple audio file formats. Each datatype is an
--   instance of Data.Binary, enabling lazy conversion to and from Lazy
--   Bytestrings using the decodeSoundFileBS function. The different
--   soundfile datatypes are generally not used directly, but are converted
--   to the generic SoundFile type.
module Sound.File

-- | Decode a Lazy ByteString to a SoundFile. This should be used instead
--   of Data.Binary decode to make sure that the correct file format is
--   used.
decodeSoundFileBS :: (Monad m) => ByteString -> AudioMonad m SoundFile

-- | Attempt to decode a soundfile as the specified type. Return Nothing on
--   failure. This function may be faster than using decodeSoundFileBS if
--   the type is known.
decodeSoundFileHinted :: (Monad m) => SndFileType -> ByteString -> AudioMonad m SoundFile

-- | Find the SndFileType of a ByteString. This function assumes that at
--   most the file will match one format. If more than one format matches,
--   the first found will be the format used.
getType :: (Monad m) => ByteString -> AudioMonad m SndFileType

-- | Attempt to guess the SndFileType from the extension of the file. This
--   does not check that the file actually is valid data.
getTypeFromName :: (Monad m) => FilePath -> AudioMonad m SndFileType

-- | Create a WaveFile from a SndFileCls
toWaveFile :: (SndFileCls a, Monad m) => a -> AudioMonad m WaveFile