Codec.Audio.FLAC.StreamEncoder

The module contains a Haskell interface to FLAC stream encoder.

How to use this module

Just call the encodeFlac function with EncoderSettings, input and output file names. The encodeFlac function only encodes vanilla WAVE and RF64.

Low-level details

The implementation uses the reference implementation of FLAC—libFLAC (C library) under the hood. This means you'll need at least version 1.3.0 of libFLAC (released 26 May 2013) installed for the binding to work.

The binding works with minimal overhead compared to the C implementation. Encoding speed is equal to that of flac command line tool. Memory consumption is minimal and remains constant regardless of size of file to decode.

Documentation

data EncoderSettings

Parameters of the stream encoder. Note that the encoderCompression parameter influences a number of other parameters on its own as specified here https://xiph.org/flac/api/group__flac__stream__encoder.html#gae49cf32f5256cb47eecd33779493ac85. The parameters that it sets automatically are wrapped in Maybes, so you can choose whether to use the value that is set by encoderCompression specifying Nothing (default), or use something specific by passing a value inside Just. Thorough understanding of the FLAC format is necessary to achieve good results, though.

Constructors

EncoderSettings

Fields

• encoderCompression :: !Word32

  Compression level [0..8], default is 5.

• encoderBlockSize :: !Word32

  Block size, default is 0.

• encoderVerify :: !Bool

  Verify result (slower), default is False.

• encoderDoMidSideStereo :: !(Maybe Bool)

  Enable mid-side encoding on stereo input. The number of channels must be 2 for this to have any effect. Default value: Nothing.

• encoderLooseMidSideStereo :: !(Maybe Bool)

  Set to True to enable adaptive switching between mid-side and left-right encoding on stereo input. Set to False to use exhaustive searching. Setting this to True requires encoderDoMidSideStereo to also be set to True in order to have any effect. Default value: Nothing.

• encoderApodization :: !(Maybe (NonEmpty ApodizationFunction))

  Sets the apodization function(s) the encoder will use when windowing audio data for LPC analysis. Up to 32 functions are kept, the rest are dropped. Import Codec.Audio.FLAC.StreamEncoder.Apodization to bring apodization functions in scope. Default value: Nothing.

• encoderMaxLpcOrder :: !(Maybe Word32)

  Set maximum LPC order, or 0 to use the fixed predictors. Default value: Nothing.

• encoderQlpCoeffPrecision :: !(Maybe Word32)

  Set the precision in bits of the quantized linear predictor coefficients, or 0 to let the encoder select it based on the blocksize. Default value: Nothing.

• encoderDoQlpCoeffPrecisionSearch :: !(Maybe Bool)

  Set to False to use only the specified quantized linear predictor coefficient precision, or True to search neighboring precision values and use the best one. Default value: Nothing.

• encoderDoExhaustiveModelSearch :: !(Maybe Bool)

  Set to False to let the encoder estimate the best model order based on the residual signal energy, or True to force the encoder to evaluate all order models and select the best. Default value: Nothing.

• encoderResidualPartitionOrders :: !(Maybe (Word32, Word32))

  Set the minimum and maximum partition order to search when coding the residual. The partition order determines the context size in the residual. The context size will be approximately blocksize / (2 ^ order). Set both min and max values to 0 to force a single context, whose Rice parameter is based on the residual signal variance. Otherwise, set a min and max order, and the encoder will search all orders, using the mean of each context for its Rice parameter, and use the best. Default: Nothing.

Instances

Eq EncoderSettings

Defined in Codec.Audio.FLAC.StreamEncoder

Methods

(==) :: EncoderSettings -> EncoderSettings -> Bool

(/=) :: EncoderSettings -> EncoderSettings -> Bool

Ord EncoderSettings

Defined in Codec.Audio.FLAC.StreamEncoder

Methods

compare :: EncoderSettings -> EncoderSettings -> Ordering

(<) :: EncoderSettings -> EncoderSettings -> Bool

(<=) :: EncoderSettings -> EncoderSettings -> Bool

(>) :: EncoderSettings -> EncoderSettings -> Bool

(>=) :: EncoderSettings -> EncoderSettings -> Bool

max :: EncoderSettings -> EncoderSettings -> EncoderSettings

min :: EncoderSettings -> EncoderSettings -> EncoderSettings

Read EncoderSettings

Defined in Codec.Audio.FLAC.StreamEncoder

Methods

readsPrec :: Int -> ReadS EncoderSettings

readList :: ReadS [EncoderSettings]

readPrec :: ReadPrec EncoderSettings

readListPrec :: ReadPrec [EncoderSettings]

Show EncoderSettings

Defined in Codec.Audio.FLAC.StreamEncoder

Methods

showsPrec :: Int -> EncoderSettings -> ShowS

show :: EncoderSettings -> String

showList :: [EncoderSettings] -> ShowS

defaultEncoderSettings :: EncoderSettings

Default EncoderSettings.

Since: 0.2.0

data EncoderException

Exception that is thrown when encoding fails for some reason.

Constructors

EncoderInvalidSampleFormat SampleFormat

Input WAVE file had this sample format, which is not supported (usually happens with floating point samples right now).

EncoderInitFailed EncoderInitStatus

Encoder initialization failed.

EncoderFailed EncoderState

Encoder failed.

Instances

Eq EncoderException

Defined in Codec.Audio.FLAC.StreamEncoder.Internal.Types

Methods

(==) :: EncoderException -> EncoderException -> Bool

(/=) :: EncoderException -> EncoderException -> Bool

Read EncoderException

Defined in Codec.Audio.FLAC.StreamEncoder.Internal.Types

Methods

readsPrec :: Int -> ReadS EncoderException

readList :: ReadS [EncoderException]

readPrec :: ReadPrec EncoderException

readListPrec :: ReadPrec [EncoderException]

Show EncoderException

Defined in Codec.Audio.FLAC.StreamEncoder.Internal.Types

Methods

showsPrec :: Int -> EncoderException -> ShowS

show :: EncoderException -> String

showList :: [EncoderException] -> ShowS

Exception EncoderException

Defined in Codec.Audio.FLAC.StreamEncoder.Internal.Types

Methods

toException :: EncoderException -> SomeException

fromException :: SomeException -> Maybe EncoderException

displayException :: EncoderException -> String

data EncoderInitStatus

Status of encoder initialization process.

Constructors

EncoderInitStatusOK

Initialization was successful.

EncoderInitStatusEncoderError

General failure to set up encoder.

EncoderInitStatusUnsupportedCointainer

The library was not compiled with support for the given container format.

EncoderInitStatusInvalidCallbacks

A required callback was not supplied.

EncoderInitStatusInvalidNumberOfChannels

The encoder has an invalid setting for the number of channels.

EncoderInitStatusInvalidBitsPerSample

The encoder has an invalid setting for the bits-per-sample. FLAC supports 4-32 bps but the reference encoder currently supports only up to 24 bps.

EncoderInitStatusInvalidSampleRate

The encoder has an invalid setting for the sample rate.

EncoderInitStatusInvalidBlockSize

The encoder has an invalid setting for the block size.

EncoderInitStatusInvalidMaxLpcOrder

The encoder has an invalid setting for the maximum LPC order.

EncoderInitStatusInvalidQlpCoeffPrecision

The encoder has an invalid setting for the precision of the quantized linear predictor coefficients.

EncoderInitStatusBlockSizeTooSmallForLpcOrder

The specified block size is less than the maximum LPC order.

EncoderInitStatusNotStreamable

The encoder is bound to the Subset but other settings violate it.

EncoderInitStatusInvalidMetadata

The metadata input to the encoder is invalid (should never happen with this binding).

EncoderInitStatusAlreadyInitialized

Initialization was attempted on already initialized encoder.

Instances

Bounded EncoderInitStatus

Defined in Codec.Audio.FLAC.StreamEncoder.Internal.Types

Methods

minBound :: EncoderInitStatus

maxBound :: EncoderInitStatus

Enum EncoderInitStatus

Defined in Codec.Audio.FLAC.StreamEncoder.Internal.Types

Methods

succ :: EncoderInitStatus -> EncoderInitStatus

pred :: EncoderInitStatus -> EncoderInitStatus

toEnum :: Int -> EncoderInitStatus

fromEnum :: EncoderInitStatus -> Int

enumFrom :: EncoderInitStatus -> [EncoderInitStatus]

enumFromThen :: EncoderInitStatus -> EncoderInitStatus -> [EncoderInitStatus]

enumFromTo :: EncoderInitStatus -> EncoderInitStatus -> [EncoderInitStatus]

enumFromThenTo :: EncoderInitStatus -> EncoderInitStatus -> EncoderInitStatus -> [EncoderInitStatus]

Eq EncoderInitStatus

Defined in Codec.Audio.FLAC.StreamEncoder.Internal.Types

Methods

(==) :: EncoderInitStatus -> EncoderInitStatus -> Bool

(/=) :: EncoderInitStatus -> EncoderInitStatus -> Bool

Ord EncoderInitStatus

Defined in Codec.Audio.FLAC.StreamEncoder.Internal.Types

Methods

compare :: EncoderInitStatus -> EncoderInitStatus -> Ordering

(<) :: EncoderInitStatus -> EncoderInitStatus -> Bool

(<=) :: EncoderInitStatus -> EncoderInitStatus -> Bool

(>) :: EncoderInitStatus -> EncoderInitStatus -> Bool

(>=) :: EncoderInitStatus -> EncoderInitStatus -> Bool

max :: EncoderInitStatus -> EncoderInitStatus -> EncoderInitStatus

min :: EncoderInitStatus -> EncoderInitStatus -> EncoderInitStatus

Read EncoderInitStatus

Defined in Codec.Audio.FLAC.StreamEncoder.Internal.Types

Methods

readsPrec :: Int -> ReadS EncoderInitStatus

readList :: ReadS [EncoderInitStatus]

readPrec :: ReadPrec EncoderInitStatus

readListPrec :: ReadPrec [EncoderInitStatus]

Show EncoderInitStatus

Defined in Codec.Audio.FLAC.StreamEncoder.Internal.Types

Methods

showsPrec :: Int -> EncoderInitStatus -> ShowS

show :: EncoderInitStatus -> String

showList :: [EncoderInitStatus] -> ShowS

data EncoderState

Enumeration of encoder states.

Constructors

EncoderStateOK

The encoder is in the normal OK state and samples can be processed.

EncoderStateUninitialized

The encoder is in the uninitialized state.

EncoderStateOggError

An error occurred in the underlying Ogg layer.

EncoderStateVerifyDecoderError

An error occurred in the underlying verify stream decoder.

EncoderStateVerifyMismatchInAudioData

The verify decoder detected a mismatch between the original audio signal and the decoded audio signal.

EncoderStateClientError

One of the callbacks returned a fatal error.

EncoderStateIOError

An I/O error occurred while opening/reading/writing a file.

EncoderStateFramingError

An error occurred while writing the stream.

EncoderStateMemoryAllocationError

Memory allocation failed.

Instances

Bounded EncoderState

Defined in Codec.Audio.FLAC.StreamEncoder.Internal.Types

Methods

minBound :: EncoderState

maxBound :: EncoderState

Enum EncoderState

Defined in Codec.Audio.FLAC.StreamEncoder.Internal.Types

Methods

succ :: EncoderState -> EncoderState

pred :: EncoderState -> EncoderState

toEnum :: Int -> EncoderState

fromEnum :: EncoderState -> Int

enumFrom :: EncoderState -> [EncoderState]

enumFromThen :: EncoderState -> EncoderState -> [EncoderState]

enumFromTo :: EncoderState -> EncoderState -> [EncoderState]

enumFromThenTo :: EncoderState -> EncoderState -> EncoderState -> [EncoderState]

Eq EncoderState

Defined in Codec.Audio.FLAC.StreamEncoder.Internal.Types

Methods

(==) :: EncoderState -> EncoderState -> Bool

(/=) :: EncoderState -> EncoderState -> Bool

Ord EncoderState

Defined in Codec.Audio.FLAC.StreamEncoder.Internal.Types

Methods

compare :: EncoderState -> EncoderState -> Ordering

(<) :: EncoderState -> EncoderState -> Bool

(<=) :: EncoderState -> EncoderState -> Bool

(>) :: EncoderState -> EncoderState -> Bool

(>=) :: EncoderState -> EncoderState -> Bool

max :: EncoderState -> EncoderState -> EncoderState

min :: EncoderState -> EncoderState -> EncoderState

Read EncoderState

Defined in Codec.Audio.FLAC.StreamEncoder.Internal.Types

Methods

readsPrec :: Int -> ReadS EncoderState

readList :: ReadS [EncoderState]

readPrec :: ReadPrec EncoderState

readListPrec :: ReadPrec [EncoderState]

Show EncoderState

Defined in Codec.Audio.FLAC.StreamEncoder.Internal.Types

Methods

showsPrec :: Int -> EncoderState -> ShowS

show :: EncoderState -> String

showList :: [EncoderState] -> ShowS

encodeFlac

Arguments

:: MonadIO m

=> EncoderSettings

Encoder settings

-> FilePath

File to encode

-> FilePath

Where to save the resulting FLAC file

-> m ()

Encode a WAVE file or RF64 file to native FLAC.

If the input file is not a valid WAVE file, WaveException will be thrown. EncoderException is thrown when underlying FLAC encoder reports a problem.

Please note that there are a number of limitations on parameters of input audio stream (imposed by current reference FLAC implementation):

• Number of channels may be only 1–8 inclusive.
• Supported values for bits per sample are 4–24 inclusive.
• Acceptable sample rate lies in the range 1–655350 inclusive.