Copyright	© 2016–2017 Mark Karpov
License	BSD 3 clause
Maintainer	Mark Karpov <markkarpov92@gmail.com>
Stability	experimental
Portability	portable
Safe Haskell	None
Language	Haskell2010

Codec.Audio.Wave

Contents

Types
Derived information
Common speaker configurations
Reading
Writing

Description

This module provides a safe interface that allows to manipulate WAVE files in their “classic” form as well as files in the RF64 format https://tech.ebu.ch/docs/tech/tech3306-2009.pdf. RF64 adds the ability to store files larger than 4 Gb.

The main feature of the API is that it does not allow the user to duplicate information and introduce errors in that way. For example, block align may be calculated from other parameters of audio stream, thus we do not store it in the Wave record and do not allow user to specify it. We provide, however, a way to calculate it given Wave record, see waveBlockAlign. The same is done for channels. Channel mask is a more general means of providing information about number of channels and corresponding speaker positions, thus we only store channel mask in user-friendly form, and number of channels can be derived from that information.

Another feature of the library is that it does not dictate how to read/write audio data. What we give is the information about audio data and offset in file where it begins. To write data the user may use a callback that receives a Handle as an argument. Size of data block is deduced automatically for you. Exclusion of audio data from consideration makes the library pretty fast and open to different ways to handle audio data itself, including using foreign code (such as C).

The library provides control over all parts of WAVE file that may be of interest. In particular, it even allows to write arbitrary chunks between fmt and data chunks, although it's rarely useful (and may actually confuse buggy applications that don't know how to skip unknown chunks).

Synopsis

Types

data Wave #

Representation of “essential” information about a WAVE file. Every field in this record provides orthogonal piece of information, so no field can be calculated from other fields. The fields are complemented by the following functions that calculate some derivative parameters: waveByteRate, waveBitRate, waveBitsPerSample, waveBlockAlign, and waveChannels.

Constructors

Wave

Fields

waveFileFormat :: !WaveFormat
Format of file this Wave record was extracted/to be written to, WaveFormat. Default value is: WaveVanilla.
waveSampleRate :: !Word32
Sample rate in Hz, default is: 44100.
waveSampleFormat :: !SampleFormat
Sample format. The library supports signed/unsigned integers and floats. Default value: SampleFormatPcmInt 16.
waveChannelMask :: !(Set SpeakerPosition)
The channel mask as a Set of SpeakerPositions. Default value is speakerStereo.
waveDataOffset :: !Word32
Offset in bytes from the beginning of file where actual sample data begins. Default value: 0.
waveDataSize :: !Word64
Size of audio data in bytes. Default value: 0.
waveSamplesTotal :: !Word64
Total number of samples in the audio stream. “Samples” here mean multi-channel samples, so one second of 44.1 kHz audio will have 44100 samples regardless of the number of channels. For PCM format it's deduced from size of data-block, for other formats it's read from/written to the “fact” chunk. Default value: 0.
waveOtherChunks :: [(ByteString, ByteString)]
Other chunks as (tag, body) pairs. Only first four bytes of tag are significant (and it must be four bytes long, if it's too short it will be padded by null bytes). Default value: [].

Instances

Eq Wave #
Methods (==) :: Wave -> Wave -> Bool # (/=) :: Wave -> Wave -> Bool #
Data Wave #
Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Wave -> c Wave # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Wave # toConstr :: Wave -> Constr # dataTypeOf :: Wave -> DataType # dataCast1 :: Typeable (* -> ) t => (forall d. Data d => c (t d)) -> Maybe (c Wave) # dataCast2 :: Typeable ( -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Wave) # gmapT :: (forall b. Data b => b -> b) -> Wave -> Wave # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Wave -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Wave -> r # gmapQ :: (forall d. Data d => d -> u) -> Wave -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Wave -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Wave -> m Wave # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Wave -> m Wave # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Wave -> m Wave #
Ord Wave #
Methods compare :: Wave -> Wave -> Ordering # (<) :: Wave -> Wave -> Bool # (<=) :: Wave -> Wave -> Bool # (>) :: Wave -> Wave -> Bool # (>=) :: Wave -> Wave -> Bool # max :: Wave -> Wave -> Wave # min :: Wave -> Wave -> Wave #
Read Wave #
Methods readsPrec :: Int -> ReadS Wave # readList :: ReadS [Wave] # readPrec :: ReadPrec Wave # readListPrec :: ReadPrec [Wave] #
Show Wave #
Methods showsPrec :: Int -> Wave -> ShowS # show :: Wave -> String # showList :: [Wave] -> ShowS #
Default Wave #
Methods def :: Wave #

data WaveFormat #

WaveFormat as flavor of WAVE file.

Constructors

WaveVanilla	Classic WAVE file, 4 Gb size limitation
WaveRF64	WAVE file with RF64 extension

Instances

Bounded WaveFormat #
Methods minBound :: WaveFormat # maxBound :: WaveFormat #
Enum WaveFormat #
Methods succ :: WaveFormat -> WaveFormat # pred :: WaveFormat -> WaveFormat # toEnum :: Int -> WaveFormat # fromEnum :: WaveFormat -> Int # enumFrom :: WaveFormat -> [WaveFormat] # enumFromThen :: WaveFormat -> WaveFormat -> [WaveFormat] # enumFromTo :: WaveFormat -> WaveFormat -> [WaveFormat] # enumFromThenTo :: WaveFormat -> WaveFormat -> WaveFormat -> [WaveFormat] #
Eq WaveFormat #
Methods (==) :: WaveFormat -> WaveFormat -> Bool # (/=) :: WaveFormat -> WaveFormat -> Bool #
Data WaveFormat #
Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> WaveFormat -> c WaveFormat # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c WaveFormat # toConstr :: WaveFormat -> Constr # dataTypeOf :: WaveFormat -> DataType # dataCast1 :: Typeable (* -> ) t => (forall d. Data d => c (t d)) -> Maybe (c WaveFormat) # dataCast2 :: Typeable ( -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c WaveFormat) # gmapT :: (forall b. Data b => b -> b) -> WaveFormat -> WaveFormat # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> WaveFormat -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> WaveFormat -> r # gmapQ :: (forall d. Data d => d -> u) -> WaveFormat -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> WaveFormat -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> WaveFormat -> m WaveFormat # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> WaveFormat -> m WaveFormat # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> WaveFormat -> m WaveFormat #
Ord WaveFormat #
Methods compare :: WaveFormat -> WaveFormat -> Ordering # (<) :: WaveFormat -> WaveFormat -> Bool # (<=) :: WaveFormat -> WaveFormat -> Bool # (>) :: WaveFormat -> WaveFormat -> Bool # (>=) :: WaveFormat -> WaveFormat -> Bool # max :: WaveFormat -> WaveFormat -> WaveFormat # min :: WaveFormat -> WaveFormat -> WaveFormat #
Read WaveFormat #
Methods readsPrec :: Int -> ReadS WaveFormat # readList :: ReadS [WaveFormat] # readPrec :: ReadPrec WaveFormat # readListPrec :: ReadPrec [WaveFormat] #
Show WaveFormat #
Methods showsPrec :: Int -> WaveFormat -> ShowS # show :: WaveFormat -> String # showList :: [WaveFormat] -> ShowS #

data SampleFormat #

Sample formats with associated bit depth (when variable).

Constructors

SampleFormatPcmInt Word16	Unsigned/signed integers, the argument is the number of bits per sample (8 bit and less are encoded as unsigned integers).
SampleFormatIeeeFloat32Bit	Samples are 32 bit floating point numbers.
SampleFormatIeeeFloat64Bit	Samples are 64 bit floating point numbers.

Instances

Eq SampleFormat #
Methods (==) :: SampleFormat -> SampleFormat -> Bool # (/=) :: SampleFormat -> SampleFormat -> Bool #
Data SampleFormat #
Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> SampleFormat -> c SampleFormat # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c SampleFormat # toConstr :: SampleFormat -> Constr # dataTypeOf :: SampleFormat -> DataType # dataCast1 :: Typeable (* -> ) t => (forall d. Data d => c (t d)) -> Maybe (c SampleFormat) # dataCast2 :: Typeable ( -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c SampleFormat) # gmapT :: (forall b. Data b => b -> b) -> SampleFormat -> SampleFormat # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> SampleFormat -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> SampleFormat -> r # gmapQ :: (forall d. Data d => d -> u) -> SampleFormat -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> SampleFormat -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> SampleFormat -> m SampleFormat # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> SampleFormat -> m SampleFormat # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> SampleFormat -> m SampleFormat #
Ord SampleFormat #
Methods compare :: SampleFormat -> SampleFormat -> Ordering # (<) :: SampleFormat -> SampleFormat -> Bool # (<=) :: SampleFormat -> SampleFormat -> Bool # (>) :: SampleFormat -> SampleFormat -> Bool # (>=) :: SampleFormat -> SampleFormat -> Bool # max :: SampleFormat -> SampleFormat -> SampleFormat # min :: SampleFormat -> SampleFormat -> SampleFormat #
Read SampleFormat #
Methods readsPrec :: Int -> ReadS SampleFormat # readList :: ReadS [SampleFormat] # readPrec :: ReadPrec SampleFormat # readListPrec :: ReadPrec [SampleFormat] #
Show SampleFormat #
Methods showsPrec :: Int -> SampleFormat -> ShowS # show :: SampleFormat -> String # showList :: [SampleFormat] -> ShowS #

data SpeakerPosition #

Speaker positions clarifying which exactly channels are packed in the WAVE file.

Constructors

SpeakerFrontLeft	Front left
SpeakerFrontRight	Front right
SpeakerFrontCenter	Front center
SpeakerLowFrequency	Sub-woofer
SpeakerBackLeft	Back left
SpeakerBackRight	Back right
SpeakerFrontLeftOfCenter	Front left of center
SpeakerFrontRightOfCenter	Front right of center
SpeakerBackCenter	Back center
SpeakerSideLeft	Side left
SpeakerSideRight	Side right
SpeakerTopCenter	Top center
SpeakerTopFrontLeft	Top front left
SpeakerTopFrontCenter	Top front center
SpeakerTopFrontRight	Top front right
SpeakerTopBackLeft	Top back left
SpeakerTopBackCenter	Top back center
SpeakerTopBackRight	Top back right

Instances

Bounded SpeakerPosition #
Methods minBound :: SpeakerPosition # maxBound :: SpeakerPosition #
Enum SpeakerPosition #
Methods succ :: SpeakerPosition -> SpeakerPosition # pred :: SpeakerPosition -> SpeakerPosition # toEnum :: Int -> SpeakerPosition # fromEnum :: SpeakerPosition -> Int # enumFrom :: SpeakerPosition -> [SpeakerPosition] # enumFromThen :: SpeakerPosition -> SpeakerPosition -> [SpeakerPosition] # enumFromTo :: SpeakerPosition -> SpeakerPosition -> [SpeakerPosition] # enumFromThenTo :: SpeakerPosition -> SpeakerPosition -> SpeakerPosition -> [SpeakerPosition] #
Eq SpeakerPosition #
Methods (==) :: SpeakerPosition -> SpeakerPosition -> Bool # (/=) :: SpeakerPosition -> SpeakerPosition -> Bool #
Data SpeakerPosition #
Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> SpeakerPosition -> c SpeakerPosition # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c SpeakerPosition # toConstr :: SpeakerPosition -> Constr # dataTypeOf :: SpeakerPosition -> DataType # dataCast1 :: Typeable (* -> ) t => (forall d. Data d => c (t d)) -> Maybe (c SpeakerPosition) # dataCast2 :: Typeable ( -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c SpeakerPosition) # gmapT :: (forall b. Data b => b -> b) -> SpeakerPosition -> SpeakerPosition # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> SpeakerPosition -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> SpeakerPosition -> r # gmapQ :: (forall d. Data d => d -> u) -> SpeakerPosition -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> SpeakerPosition -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> SpeakerPosition -> m SpeakerPosition # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> SpeakerPosition -> m SpeakerPosition # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> SpeakerPosition -> m SpeakerPosition #
Ord SpeakerPosition #
Methods compare :: SpeakerPosition -> SpeakerPosition -> Ordering # (<) :: SpeakerPosition -> SpeakerPosition -> Bool # (<=) :: SpeakerPosition -> SpeakerPosition -> Bool # (>) :: SpeakerPosition -> SpeakerPosition -> Bool # (>=) :: SpeakerPosition -> SpeakerPosition -> Bool # max :: SpeakerPosition -> SpeakerPosition -> SpeakerPosition # min :: SpeakerPosition -> SpeakerPosition -> SpeakerPosition #
Read SpeakerPosition #
Methods readsPrec :: Int -> ReadS SpeakerPosition # readList :: ReadS [SpeakerPosition] # readPrec :: ReadPrec SpeakerPosition # readListPrec :: ReadPrec [SpeakerPosition] #
Show SpeakerPosition #
Methods showsPrec :: Int -> SpeakerPosition -> ShowS # show :: SpeakerPosition -> String # showList :: [SpeakerPosition] -> ShowS #

data WaveException #

Exceptions the library can throw.

Constructors

BadFileFormat String FilePath	Format of given file doesn't look like anything familiar. The first argument is a message explaining what's wrong and the second argument is the file name.
NonDataChunkIsTooLong ByteString FilePath	The library found a chunk which is not a `data` chunk but is way too long. The first argument is the tag of the chunk and the second argument is the file name.
NonPcmFormatButMissingFact FilePath	The specified format is non-PCM, it's vanilla WAVE, but “fact” chunk is missing.

Instances

Eq WaveException #
Methods (==) :: WaveException -> WaveException -> Bool # (/=) :: WaveException -> WaveException -> Bool #
Data WaveException #
Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> WaveException -> c WaveException # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c WaveException # toConstr :: WaveException -> Constr # dataTypeOf :: WaveException -> DataType # dataCast1 :: Typeable (* -> ) t => (forall d. Data d => c (t d)) -> Maybe (c WaveException) # dataCast2 :: Typeable ( -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c WaveException) # gmapT :: (forall b. Data b => b -> b) -> WaveException -> WaveException # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> WaveException -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> WaveException -> r # gmapQ :: (forall d. Data d => d -> u) -> WaveException -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> WaveException -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> WaveException -> m WaveException # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> WaveException -> m WaveException # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> WaveException -> m WaveException #
Read WaveException #
Methods readsPrec :: Int -> ReadS WaveException # readList :: ReadS [WaveException] # readPrec :: ReadPrec WaveException # readListPrec :: ReadPrec [WaveException] #
Show WaveException #
Methods showsPrec :: Int -> WaveException -> ShowS # show :: WaveException -> String # showList :: [WaveException] -> ShowS #
Exception WaveException #
Methods toException :: WaveException -> SomeException # fromException :: SomeException -> Maybe WaveException # displayException :: WaveException -> String #

Derived information

waveByteRate :: Wave -> Word32 #

Byte rate of a given Wave file. Byte rate is the number of bytes it takes to encode one second of audio.

waveBitRate :: Wave -> Double #

Bit rate in kilobits per second.

waveBitsPerSample :: Wave -> Word16 #

Number of significant bits in every sample.

waveBlockAlign :: Wave -> Word16 #

Block alignment of samples as number of bits per sample (rounded towards next multiplier of 8 if necessary) multiplied by number of channels. This is how many bytes it takes to encode a single multi-channel sample.

waveChannels :: Wave -> Word16 #

Total number of channels present in the audio stream.

waveDuration :: Wave -> Double #

Duration in seconds.

Common speaker configurations

speakerMono :: Set SpeakerPosition #

Front center (C).

speakerStereo :: Set SpeakerPosition #

Front left (L), front right (R).

speakerQuad :: Set SpeakerPosition #

L, R, back left (Lb), back right (Rb).

speakerSurround :: Set SpeakerPosition #

Surround: L, R, front center (C), back center (Cb).

speaker5_1 :: Set SpeakerPosition #

L, R, C, Lb, Rb, low frequency (LFE).

speaker7_1 :: Set SpeakerPosition #

L, R, C, Lb, Rb, front left-of-center, front right-of-center, LFE.

speaker5_1Surround :: Set SpeakerPosition #

L, R, C, side left (Ls), side right (Rs), LFE.

speaker7_1Surround :: Set SpeakerPosition #

L, R, C, Lb, Rb, Ls, Rs, LFE.

Reading

readWaveFile #

Arguments

:: MonadIO m
=> FilePath	Location of file to read
-> m Wave

Read Wave record from a WAVE file found at given path. This action throws WaveException if the file is malformed and cannot be read.

You can feed vanilla WAVE and RF64 files. The actual format is detected automatically from the contents of the file, not by extension.

PCM with samples in form of integers and floats only are supported, see SampleFormat. Addition of other formats will be performed on request, please feel free to contact me at https://github.com/mrkkrp/wave/issues.

Finally, if “fmt” chunk is not extensible, we try to guess channel mask from number of channels alone, here is how:

1 channel: front center (C)
2 channels: front left (L), front right (R)
3 channels: L, R, C
4 channels: L, R, back left (Lb), back right (Rb)
5 channels: L, R, C, Lb, Rb
6 channels: L, R, C, LFE, Lb, Rb
7 channels: L, R, C, LFE, back center (Cb), side left (Ls), side right (Rs)
8 channels: L, R, C, LFE, Lb, Rb, Ls, Rs
N channels: first N items are taken from [minBound..maxBound] of SpeakerPositions

Writing

writeWaveFile #

Arguments

:: MonadIO m
=> FilePath	Where to save the file
-> Wave	Parameters of the WAVE file
-> (Handle -> IO ())	Callback that will be used to write WAVE data
-> m ()

Write a WAVE file. The waveFileFormat value specifies in which of the supported formats the file should be written. The action uses the provided callback to write WAVE audio data. waveDataOffset and waveDataSize from Wave are ignored, instead the values are inferred dynamically after using the callback. Further, the function takes care of the requirement that WAVE data should end on “even byte boundary”. The pad byte is written for you if necessary and included in the data size.

The waveSamplesTotal field will be inferred for PCM (including formats with samples represented as floats, i.e. always right now), so the provided value is not used.

If Wave specifies floating point sample format, the “fact” chunk is automatically generated and written (the chunk is required for all non-PCM formats by the spec), but only for vanilla WAVE.