Codec.Audio.Wave

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).

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.