-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Complete high-level binding to libFLAC
--
-- Complete high-level binding to libFLAC.
@package flac
@version 0.1.1
-- | This module exports the ApodizationFunction data type, which is
-- rarely needed, and thus should not “contaminate” the
-- Codec.Audio.FLAC.StreamEncoder module with potentially
-- confilcting names.
module Codec.Audio.FLAC.StreamEncoder.Apodization
-- | Supported apodization functions.
data ApodizationFunction
Bartlett :: ApodizationFunction
BartlettHann :: ApodizationFunction
Blackman :: ApodizationFunction
BlackmanHarris4Term92Db :: ApodizationFunction
Connes :: ApodizationFunction
Flattop :: ApodizationFunction
-- | The parameter is standard deviation STDDEV, 0 < STDDEV
-- <= 0.5.
Gauss :: Double -> ApodizationFunction
Hamming :: ApodizationFunction
Hann :: ApodizationFunction
KaiserBessel :: ApodizationFunction
Nuttall :: ApodizationFunction
Rectangle :: ApodizationFunction
Triangle :: ApodizationFunction
-- | The parameter is the fraction of the window that is tapered
-- P, 0 <= P <= 1. P == 0 corresponds to
-- Rectangle and P = 1 corresponds to Hann.
Tukey :: Double -> ApodizationFunction
-- | The parameters are a series of small windows (all treated separately).
-- The three parameters are n, ov and P.
-- n is the number of functions to add, ov is the
-- overlap of the windows. P is the fraction of the window that
-- is tapered, like with a regular tukey window. The function can be
-- specified with only a number, a number and an overlap, or a number, an
-- overlap and a P. ov should be smaller than 1 and can
-- be negative.
PartialTukey :: Natural -> (Maybe (Double, Maybe Double)) -> ApodizationFunction
-- | The parameters are a series of windows that have a hole in them. In
-- this way, the predictor is constructed with only a part of the block,
-- which helps in case a block consists of dissimilar parts. All said
-- about the parameters in the comment for PartialTukey applies
-- here, with the exception that ov is the overlap in the gaps
-- in this case.
PunchoutTukey :: Natural -> (Maybe (Double, Maybe Double)) -> ApodizationFunction
Welch :: ApodizationFunction
-- | 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 pure 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.
module Codec.Audio.FLAC.StreamEncoder
-- | Parameters of 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.
data EncoderSettings
EncoderSettings :: !Word32 -> !Word32 -> !Bool -> !(Maybe Bool) -> !(Maybe Bool) -> !(Maybe (NonEmpty ApodizationFunction)) -> !(Maybe Word32) -> !(Maybe Word32) -> !(Maybe Bool) -> !(Maybe Bool) -> !(Maybe (Word32, Word32)) -> EncoderSettings
-- | Compression level [0..8], default is 5.
[encoderCompression] :: EncoderSettings -> !Word32
-- | Block size, default is 0.
[encoderBlockSize] :: EncoderSettings -> !Word32
-- | Verify result (slower), default is False.
[encoderVerify] :: EncoderSettings -> !Bool
-- | Enable mid-side encoding on stereo input. The number of channels must
-- be 2 for this to have any effect. Default value: Nothing.
[encoderDoMidSideStereo] :: EncoderSettings -> !(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.
[encoderLooseMidSideStereo] :: EncoderSettings -> !(Maybe Bool)
-- | 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.
[encoderApodization] :: EncoderSettings -> !(Maybe (NonEmpty ApodizationFunction))
-- | Set maximum LPC order, or 0 to use the fixed predictors. Default
-- value: Nothing.
[encoderMaxLpcOrder] :: EncoderSettings -> !(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.
[encoderQlpCoeffPrecision] :: EncoderSettings -> !(Maybe Word32)
-- | 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.
[encoderDoQlpCoeffPrecisionSearch] :: EncoderSettings -> !(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.
[encoderDoExhaustiveModelSearch] :: EncoderSettings -> !(Maybe Bool)
-- | 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.
[encoderResidualPartitionOrders] :: EncoderSettings -> !(Maybe (Word32, Word32))
-- | Exception that is thrown when encoding fails for some reason.
data EncoderException
-- | Input WAVE file had this sample format, which is not supported
-- (usually happens with floating point samples right now).
EncoderInvalidSampleFormat :: SampleFormat -> EncoderException
-- | Encoder initialization failed.
EncoderInitFailed :: EncoderInitStatus -> EncoderException
-- | Encoder failed.
EncoderFailed :: EncoderState -> EncoderException
-- | Status of encoder initialization process.
data EncoderInitStatus
-- | Initialization was successful.
EncoderInitStatusOK :: EncoderInitStatus
-- | General failure to set up encoder.
EncoderInitStatusEncoderError :: EncoderInitStatus
-- | The library was not compiled with support for the given container
-- format.
EncoderInitStatusUnsupportedCointainer :: EncoderInitStatus
-- | A required callback was not supplied.
EncoderInitStatusInvalidCallbacks :: EncoderInitStatus
-- | The encoder has an invalid setting for number of channels.
EncoderInitStatusInvalidNumberOfChannels :: EncoderInitStatus
-- | The encoder has an invalid setting for bits-per-sample. FLAC supports
-- 4-32 bps but the reference encoder currently supports only up to 24
-- bps.
EncoderInitStatusInvalidBitsPerSample :: EncoderInitStatus
-- | The encoder has an invalid setting for the sample rate.
EncoderInitStatusInvalidSampleRate :: EncoderInitStatus
-- | The encoder has an invalid setting for the block size.
EncoderInitStatusInvalidBlockSize :: EncoderInitStatus
-- | The encoder has an invalid setting for the maximum LPC order.
EncoderInitStatusInvalidMaxLpcOrder :: EncoderInitStatus
-- | The encoder has an invalid setting for the precision of the quantized
-- linear predictor coefficients.
EncoderInitStatusInvalidQlpCoeffPrecision :: EncoderInitStatus
-- | The specified block size is less than the maximum LPC order.
EncoderInitStatusBlockSizeTooSmallForLpcOrder :: EncoderInitStatus
-- | The encoder is bound to the Subset but other settings violate it.
EncoderInitStatusNotStreamable :: EncoderInitStatus
-- | The metadata input to the encoder is invalid (should never happen with
-- this binding).
EncoderInitStatusInvalidMetadata :: EncoderInitStatus
-- | Initialization was attempted on already initialized encoder.
EncoderInitStatusAlreadyInitialized :: EncoderInitStatus
-- | Enumeration of encoder states.
data EncoderState
-- | The encoder is in the normal OK state and samples can be processed.
EncoderStateOK :: EncoderState
-- | The encoder is in the uninitialized state.
EncoderStateUninitialized :: EncoderState
-- | An error occurred in the underlying Ogg layer.
EncoderStateOggError :: EncoderState
-- | An error occurred in the underlying verify stream decoder.
EncoderStateVerifyDecoderError :: EncoderState
-- | The verify decoder detected a mismatch between the original audio
-- signal and the decoded audio signal.
EncoderStateVerifyMismatchInAudioData :: EncoderState
-- | One of the callbacks returned a fatal error.
EncoderStateClientError :: EncoderState
-- | An I/O error occurred while opening/reading/writing a file.
EncoderStateIOError :: EncoderState
-- | An error occurred while writing the stream.
EncoderStateFramingError :: EncoderState
-- | Memory allocation failed.
EncoderStateMemoryAllocationError :: EncoderState
-- | 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.
--
encodeFlac :: MonadIO m => EncoderSettings -> FilePath -> FilePath -> m ()
instance GHC.Classes.Ord Codec.Audio.FLAC.StreamEncoder.EncoderSettings
instance GHC.Classes.Eq Codec.Audio.FLAC.StreamEncoder.EncoderSettings
instance GHC.Read.Read Codec.Audio.FLAC.StreamEncoder.EncoderSettings
instance GHC.Show.Show Codec.Audio.FLAC.StreamEncoder.EncoderSettings
instance Data.Default.Class.Default Codec.Audio.FLAC.StreamEncoder.EncoderSettings
-- | This module exports the CueSheetData and CueTrack data
-- types, which are rarely needed, and thus should not “contaminate” the
-- Codec.Audio.Metadata module with potentially conflicting names.
module Codec.Audio.FLAC.Metadata.CueSheet
-- | The data type represents CUE sheet as stored in FLAC metadata. This
-- differs from traditional CUE sheets stored in “.cue” files (see
-- https://hackage.haskell.org/package/cue-sheet to work with
-- those).
data CueSheetData
CueSheetData :: !ByteString -> !Word64 -> !Bool -> ![CueTrack] -> !CueTrack -> CueSheetData
-- | Media catalog number, in ASCII printable characters 0x20-0x7e. In
-- general, the media catalog number may be 0 to 128 bytes long; any
-- unused characters will be right-padded with NUL characters. For CD-DA,
-- this is a thirteen digit number.
[cueCatalog] :: CueSheetData -> !ByteString
-- | The number of lead-in samples. This field has meaning only for CD-DA
-- CUE sheets; for other uses it should be 0. For CD-DA, the lead-in is
-- the TRACK 00 area where the table of contents is stored; more
-- precisely, it is the number of samples from the first sample of the
-- media to the first sample of the first index point of the first track.
-- According to the Red Book, the lead-in must be silence and CD grabbing
-- software does not usually store it; additionally, the lead-in must be
-- at least two seconds but may be longer. For these reasons the lead-in
-- length is stored here so that the absolute position of the first track
-- can be computed. Note that the lead-in stored here is the number of
-- samples up to the first index point of the first track, not
-- necessarily to INDEX 01 of the first track; even the first track may
-- have INDEX 00 data.
[cueLeadIn] :: CueSheetData -> !Word64
-- | True if CUE sheet corresponds to a Compact Disc, else
-- False.
[cueIsCd] :: CueSheetData -> !Bool
-- | Collection of actual tracks in the CUE sheet, see CueTrack.
[cueTracks] :: CueSheetData -> ![CueTrack]
-- | The obligatory lead-out track, will be written with index 170.
[cueLeadOutTrack] :: CueSheetData -> !CueTrack
-- | Data type representing a single track is CUE sheet.
data CueTrack
CueTrack :: !Word64 -> !ByteString -> !Bool -> !Bool -> !(Maybe Word64) -> !(NonEmpty Word64) -> CueTrack
-- | Track offset in samples, relative to the beginning of the FLAC audio
-- stream. It is the offset to the first index point of the track. (Note
-- how this differs from CD-DA, where the track's offset in the TOC is
-- that of the track's INDEX 01 even if there is an INDEX 00.) For CD-DA,
-- the offset must be evenly divisible by 588 samples (588 samples =
-- 44100 samples/sec * 1/75th of a sec).
[cueTrackOffset] :: CueTrack -> !Word64
-- | Track ISRC, empty if not present. This is a 12-digit alphanumeric
-- code, the cue-sheet package has corresponding type with smart
-- constructor and validation, but for now we don't want to depend on
-- that package.
[cueTrackIsrc] :: CueTrack -> !ByteString
-- | True for audio tracks, False for non-audio tracks.
[cueTrackAudio] :: CueTrack -> !Bool
-- | False for no pre-emphasis, True for pre-emphasis.
[cueTrackPreEmphasis] :: CueTrack -> !Bool
-- | INDEX 00 (pregap) offset, see cueTrackIndices for more info
-- about indices.
[cueTrackPregapIndex] :: CueTrack -> !(Maybe Word64)
-- | Track's index points. Offset in samples, relative to the track offset,
-- of the index point. For CD-DA, the offset must be evenly divisible by
-- 588 samples (588 samples = 44100 samples/sec * 1/75th of a sec). Note
-- that the offset is from the beginning of the track, not the beginning
-- of the audio data.
[cueTrackIndices] :: CueTrack -> !(NonEmpty Word64)
-- | The module provides a complete high-level Haskell API to manipulate
-- FLAC metadata.
--
-- How to use this module
--
-- Just like other modules of this library, the API is file-centered — no
-- streaming support is available at this time (in libFLAC as well).
-- Retrieving and editing metadata information is very easy, you only
-- need three functions: runFlacMeta, retrieve, and
-- (=->).
--
-- Here is how to get sample rate and artist name and print them:
--
--
-- import Codec.Audio.FLAC.Metadata
-- import Control.Monad.IO.Class (MonadIO (..))
-- import Data.Default.Class
--
-- main :: IO ()
-- main = runFlacMeta def "/path/to/my/file.flac" $ do
-- retrieve SampleRate >>= liftIO . print
-- retrieve (VorbisComment Artist) >>= liftIO . print
--
--
-- Normally you would just return them packed in a tuple from the monad,
-- of course. We print the values just for demonstration.
--
-- The next example shows how to set a couple of tags:
--
--
-- import Codec.Audio.FLAC.Metadata
-- import Data.Default.Class
--
-- main :: IO ()
-- main = runFlacMeta def "/path/to/my/file.flac" $ do
-- VorbisComment Artist =-> Just "Alexander Scriabin"
-- VorbisComment Title =-> Just "Sonata №9 “Black Mass”, Op. 68"
-- VorbisComment Date =-> Nothing
--
--
-- Here we write two tags using the (=->) operator and
-- delete the VorbisComment Date metadata
-- attribute by setting it to Nothing. Note that not all
-- attributes are writable, so we cannot set things like
-- SampleRate. In fact, the type system mechanics used in the
-- library prevent this.
--
-- 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.
--
-- This module in particular uses level 2 metadata interface and it's not
-- possible to choose other interface (such as level 0 and 1). This
-- should not be of any concern to end-user, however, as level 2 supports
-- more functionality than the other levels.
module Codec.Audio.FLAC.Metadata
-- | An opaque monad for reading and writing of FLAC metadata. The monad is
-- the home for retrieve and (=->) functions
-- and can be run with runFlacMeta.
data FlacMeta a
-- | Settings that control how metadata is written in FLAC file.
data MetaSettings
MetaSettings :: !Bool -> !Bool -> !Bool -> !Bool -> MetaSettings
-- | Whether to traverse all metadata blocks just before padding sorting
-- (if enabled, see metaSortPadding) and writing data to file,
-- deleting all metadata blocks that appear to be empty, e.g. vorbis
-- comment block without any comments (tags) in it. Default value:
-- True.
[metaAutoVacuum] :: MetaSettings -> !Bool
-- | Whether to attempt to sort and consolidate all padding at the end of
-- metadata section. The main purpose of this is that the padding can be
-- truncated if necessary to get more space so we can overwrite metadata
-- blocks in place instead of overwriting the entire FLAC file. Default
-- value: True.
[metaSortPadding] :: MetaSettings -> !Bool
-- | This setting enables truncation of last padding metadata block if it
-- allows to overwrite metadata in place instead of overwriting the
-- entire file. Default value: True.
[metaUsePadding] :: MetaSettings -> !Bool
-- | If True, the owner and modification time will be preserved even
-- if new FLAC file is written (this is for the cases when we need to
-- write entire FLAC file and thus a copy of the file is written).
-- Default value: True.
[metaPreserveFileStats] :: MetaSettings -> !Bool
-- | Exception that is thrown when manipulation of FLAC metadata fails for
-- some reason.
data MetaException
-- | General failure, see the attached MetaChainStatus.
MetaGeneralProblem :: MetaChainStatus -> MetaException
-- | Invalid seek table was passed to be written.
MetaInvalidSeekTable :: MetaException
-- | Invalid CUE sheet was passed to be written. The reason why the data
-- was invalid is attached.
MetaInvalidCueSheet :: Text -> MetaException
-- | Invalid picture data was passed to be written. The reason why the data
-- was invalid is attached.
MetaInvalidPicture :: Text -> MetaException
-- | Enumeration of meta chain statuses.
data MetaChainStatus
-- | The chain is in the normal OK state.
MetaChainStatusOK :: MetaChainStatus
-- | The data passed into a function violated the function's usage
-- criteria.
MetaChainStatusIllegalInput :: MetaChainStatus
-- | The chain could not open the target file.
MetaChainStatusErrorOpeningFile :: MetaChainStatus
-- | The chain could not find the FLAC signature at the start of the file.
MetaChainStatusNotFlacFile :: MetaChainStatus
-- | The chain tried to write to a file that was not writable.
MetaChainStatusNotWritable :: MetaChainStatus
-- | The chain encountered input that does not conform to the FLAC metadata
-- specification.
MetaChainStatusBadMetadata :: MetaChainStatus
-- | The chain encountered an error while reading the FLAC file.
MetaChainStatusReadError :: MetaChainStatus
-- | The chain encountered an error while seeking in the FLAC file.
MetaChainStatusSeekError :: MetaChainStatus
-- | The chain encountered an error while writing the FLAC file.
MetaChainStatusWriteError :: MetaChainStatus
-- | The chain encountered an error renaming the FLAC file.
MetaChainStatusRenameError :: MetaChainStatus
-- | The chain encountered an error removing the temporary file.
MetaChainStatusUnlinkError :: MetaChainStatus
-- | Memory allocation failed.
MetaChainStatusMemoryAllocationError :: MetaChainStatus
-- | The caller violated an assertion or an unexpected error occurred.
MetaChainStatusInternalError :: MetaChainStatus
-- | One or more of the required callbacks was NULL.
MetaChainStatusInvalidCallbacks :: MetaChainStatus
-- | This error occurs when read and write methods do not match (i.e. when
-- if you read with callbacks, you should also use function that writes
-- with callbacks).
MetaChainStatusReadWriteMismatch :: MetaChainStatus
-- | Should not ever happen when you use this binding.
MetaChainStatusWrongWriteCall :: MetaChainStatus
-- | Run an action that manipulates FLAC metadata. MetaSettings
-- control subtle and rather low-level details of metadata editing, just
-- pass def unless you know what you are doing. FilePath
-- specifies location of FLAC file to read/edit in the file system.
-- FlacMeta is a monadic action that describes what to do with
-- metadata. Compose it from retrieve and
-- (=->).
--
-- The action will throw UnicodeException if text data like Vorbis
-- Comment entries cannot be read as UTF-8-encoded value.
--
-- If a problem occurs, MetaException is thrown with attached
-- MetaChainStatus that should help investigating what went wrong.
runFlacMeta :: MonadIO m => MetaSettings -> FilePath -> FlacMeta a -> m a
-- | A class for types that specify which metadata attributes to
-- read/write. It's not expected that users of the library will define
-- new metadata attributes other than via combination of existing ones,
-- which is also useful. For example, Duration and BitRate
-- are not read from FLAC file metadata directly, but defined in terms of
-- other attributes.
class MetaValue a where type MetaType a :: * type MetaWritable a :: Constraint _ =-> _ = error "Codec.Audio.FLAC.Metadata.(=->) is not defined" where {
type family MetaType a :: *;
type family MetaWritable a :: Constraint;
}
-- | Given value that determines what to read, read it and return. Some
-- metadata may be missing, in that case the function typically returns a
-- value wrapped in Maybe.
retrieve :: MetaValue a => a -> FlacMeta (MetaType a)
-- | Given value that determines what to write and a value to write,
-- add/replace a piece of metadata information. This is how you edit
-- metadata. To delete something, set it to Nothing (well, it
-- should be something that can be missing, for example you cannot
-- delete SampleRate attribute). If MetaWritable is
-- defined, this method must be defined as well.
(=->) :: (MetaValue a, MetaWritable a) => a -> MetaType a -> FlacMeta ()
-- | Minimal block size in samples used in the stream.
--
-- Read-only attribute represented as a Word32.
data MinBlockSize
MinBlockSize :: MinBlockSize
-- | Maximal block size in samples used in the stream. Equality of minimum
-- block size and maximum block size implies a fixed-blocksize stream.
--
-- Read-only attribute represented as a Word32.
data MaxBlockSize
MaxBlockSize :: MaxBlockSize
-- | Minimal frame size in bytes used in the stream. May be 0 to imply the
-- value is not known.
--
-- Read-only attribute represented as a Word32.
data MinFrameSize
MinFrameSize :: MinFrameSize
-- | Maximal frame size in bytes used in the stream. May be 0 to imply the
-- value is not known.
--
-- Read-only attribute represented as a Word32.
data MaxFrameSize
MaxFrameSize :: MaxFrameSize
-- | Sample rate in Hz.
--
-- Read-only attribute represented as a Word32.
data SampleRate
SampleRate :: SampleRate
-- | Number of channels. FLAC supports from 1 to 8 channels.
--
-- Read-only attribute represented as a Word32.
data Channels
Channels :: Channels
-- | Channel mask specifying which speaker positions are present. This is
-- inferred from number of channels using channel assignment rules
-- described in the FLAC specification.
--
-- Read-only attribute represented as Set
-- SpeakerPosition.
data ChannelMask
ChannelMask :: ChannelMask
-- | Bits per sample (sample depth). FLAC supports from 4 to 32 bits per
-- sample. Currently the reference encoder and decoder only support up to
-- 24 bits per sample.
--
-- Read-only attribute represented as a Word32.
data BitsPerSample
BitsPerSample :: BitsPerSample
-- | Total number of samples in audio stream. “Samples” means inter-channel
-- sample, i.e. one second of 44.1 KHz audio will have 44100 samples
-- regardless of the number of channels. A value of zero here means the
-- number of total samples is unknown.
--
-- Read-only attribute represented as a Word64.
data TotalSamples
TotalSamples :: TotalSamples
-- | File size in bytes.
--
-- Read-only attribute represented as a Natural.
data FileSize
FileSize :: FileSize
-- | Bit rate in kilo-bits per second (kbps).
--
-- Read-only attribute represented as a Word32.
data BitRate
BitRate :: BitRate
-- | MD5 signature of the unencoded audio data. This allows the decoder to
-- determine if an error exists in the audio data even when the error
-- does not result in an invalid bitstream.
--
-- Read-only attribute represented as a ByteString of
-- length 16.
data MD5Sum
MD5Sum :: MD5Sum
-- | Duration in seconds.
--
-- Read-only attribute represented as a Double.
data Duration
Duration :: Duration
-- | Application metadata. The ApplicationId argument to
-- Application data constructor can be written using usual Haskell
-- syntax for String literals, just make sure to enable the
-- OverloadedStrings extension.
--
-- For the list of defined application IDs, see:
--
-- https://xiph.org/flac/id.html.
--
-- Writable optional attribute represented as a Maybe
-- ByteString.
data Application
Application :: ApplicationId -> Application
-- | A normalizing wrapper around ByteString that makes sure that
-- the ByteString inside is a valid FLAC application name. You can
-- create values of this type using Haskell string literals with
-- OverloadedStrings or with mkApplicationId. Extract the
-- inner ByteString with unApplicationId.
data ApplicationId
-- | Application id must be four bytes long. If it's too short, null bytes
-- will be appended to it to make it four bytes long. If it's too long,
-- it will be truncated.
mkApplicationId :: ByteString -> ApplicationId
-- | Get ByteString from ApplicationId.
unApplicationId :: ApplicationId -> ByteString
-- | Seek table as a Vector of SeekPoints. Seek points within
-- a table must be sorted in ascending order by sample number. If you try
-- to write an invalid seek table, MetaException will be raised
-- using MetaInvalidSeekTable constructor.
--
-- Writable optional attribute represented as a Maybe
-- (Vector SeekPoint).
data SeekTable
SeekTable :: SeekTable
-- | The datatype represents a single point in a seek table metadata block.
data SeekPoint
SeekPoint :: !Word64 -> !Word64 -> !Word32 -> SeekPoint
-- | The sample number of the target frame
[seekPointSampleNumber] :: SeekPoint -> !Word64
-- | The offset in bytes of the target frame with respect to beginning of
-- the first frame
[seekPointStreamOffset] :: SeekPoint -> !Word64
-- | The number of samples in the target frame
[seekPointFrameSamples] :: SeekPoint -> !Word32
-- | Vorbis “vendor” comment. When “Vorbis Comment” metadata block is
-- present, the “vendor” entry is always in there, so when you delete it
-- (by VorbisVendor =-> Nothing), you
-- really set it to an empty string (which is enough to trigger auto
-- vacuum feature if no other entries are detected, see
-- metaAutoVacuum).
--
-- Writable optional attribute represented as a Maybe
-- Text.
data VorbisVendor
VorbisVendor :: VorbisVendor
-- | Various Vorbis comments, see VorbisField for available field
-- names. The field names are mostly taken from here:
--
-- https://www.xiph.org/vorbis/doc/v-comment.html.
--
-- TrackTotal, DiscNumber, and Rating are popular
-- de-facto standard fields. The library also supports the standard
-- ReplayGain comments.
--
-- Writable optional attribute represented as a Maybe
-- Text.
data VorbisComment
VorbisComment :: VorbisField -> VorbisComment
-- | Enumeration of all supported filed names to index vorbis comment
-- entries.
data VorbisField
-- | Track/Work name.
Title :: VorbisField
-- | The version field may be used to differentiate multiple versions of
-- the same track title in a single collection (e.g. remix info).
Version :: VorbisField
-- | The collection name to which this track belongs
Album :: VorbisField
-- | The track number of this piece if part of a specific larger collection
-- or album.
TrackNumber :: VorbisField
-- | Total number of tracks in the collection this track belongs to.
TrackTotal :: VorbisField
-- | Disc number in a multi-disc release.
DiscNumber :: VorbisField
-- | Total number of discs in a multi-disc release.
DiscTotal :: VorbisField
-- | The artist generally considered responsible for the work. In popular
-- music this is usually the performing band or singer. For classical
-- music it would be the composer. For an audio book it would be the
-- author of the original text.
Artist :: VorbisField
-- | The artist(s) who performed the work. In classical music this would be
-- the conductor, orchestra, soloists. In an audio book it would be the
-- actor who did the reading. In popular music this is typically the same
-- as the Artist and is omitted.
Performer :: VorbisField
-- | Copyright attribution, e.g., “2001 Nobody's Band” or “1999 Jack
-- Moffitt”.
Copyright :: VorbisField
-- | License information, e.g., “All Rights Reserved”, “Any Use Permitted”,
-- a URL to a license such as a Creative Commons license or the EFF Open
-- Audio License, etc.
License :: VorbisField
-- | Name of the organization producing the track (i.e. the “record
-- label”).
Organization :: VorbisField
-- | A short text description of the contents.
Description :: VorbisField
-- | A short text indication of music genre.
Genre :: VorbisField
-- | Date the track was recorded, usually year.
Date :: VorbisField
-- | Location where track was recorded.
Location :: VorbisField
-- | Contact information for the creators or distributors of the track.
-- This could be a URL, an email address, the physical address of the
-- producing label.
Contact :: VorbisField
-- | ISRC number for the track, see http://isrc.ifpi.org/en.
ISRC :: VorbisField
-- | Rating, usually mapped as 1–5 stars with actual values “20”, “40”,
-- “60”, “80”, “100” stored.
Rating :: VorbisField
-- | Replay gain track peak, e.g. “0.99996948”.
RGTrackPeak :: VorbisField
-- | Replay gain track gain, e.g. “-7.89 dB”.
RGTrackGain :: VorbisField
-- | Replay gain album peak, e.g. “0.99996948”.
RGAlbumPeak :: VorbisField
-- | Replay gain album gain, e.g. “-7.89 dB”.
RGAlbumGain :: VorbisField
-- | A CUE sheet stored in FLAC metadata. If you try to write an invalid
-- CUE sheet MetaException will be raised with
-- MetaInvalidCueSheet constructor which includes a Text
-- value with explanation why the CUE sheet was considered invalid.
-- Import Codec.Audio.FLAC.Metadata.CueSheet to manipulate
-- CueSheetData and CueTracks.
--
-- Writable optional attribute represented as a Maybe
-- CueSheetData.
data CueSheet
CueSheet :: CueSheet
-- | Picture embedded in FLAC file. A FLAC file can have several pictures
-- attached to it, you choose which one you want by specifying
-- PictureType. If you try to write an invalid picture
-- MetaException will be raised with MetaInvalidPicture
-- constructor which includes a Text value with explanation why
-- the picture was considered invalid.
--
-- Note that the flac-picture
-- https://hackage.haskell.org/package/flac-picture package allows
-- to work with PictureData easier using the Juicy-Pixels
-- library.
--
-- Writable optional attribute represented as a Maybe
-- PictureData.
data Picture
Picture :: PictureType -> Picture
-- | Type of picture FLAC metadata can contain. There may be several
-- metadata blocks containing pictures of different “types”.
data PictureType
-- | Other
PictureOther :: PictureType
-- | 32×32 pixels file icon (PNG only)
PictureFileIconStandard :: PictureType
-- | Other file icon
PictureFileIcon :: PictureType
-- | Cover (front)
PictureFrontCover :: PictureType
-- | Cover (back)
PictureBackCover :: PictureType
-- | Leaflet page
PictureLeafletPage :: PictureType
-- | Media (e.g. label side of CD)
PictureMedia :: PictureType
-- | Lead artist/lead performer/soloist
PictureLeadArtist :: PictureType
-- | Artist/performer
PictureArtist :: PictureType
-- | Conductor
PictureConductor :: PictureType
-- | Band/orchestra
PictureBand :: PictureType
-- | Composer
PictureComposer :: PictureType
-- | Lyricist/text writer
PictureLyricist :: PictureType
-- | Recording location
PictureRecordingLocation :: PictureType
-- | During recording
PictureDuringRecording :: PictureType
-- | During performance
PictureDuringPerformance :: PictureType
-- | Movie/video screen capture
PictureVideoScreenCapture :: PictureType
-- | A bright coloured fish
PictureFish :: PictureType
-- | Illustration
PictureIllustration :: PictureType
-- | Band/artist logotype
PictureBandLogotype :: PictureType
-- | Publisher/studio logotype
PicturePublisherLogotype :: PictureType
-- | Representation of picture contained in a FLAC metadata block.
data PictureData
PictureData :: !Text -> !Text -> !Word32 -> !Word32 -> !Word32 -> !Word32 -> !ByteString -> PictureData
-- | The picture's MIME data. For best compatibility with players, use
-- picture data of MIME type image/jpeg or image/png.
[pictureMimeType] :: PictureData -> !Text
-- | Picture's description.
[pictureDescription] :: PictureData -> !Text
-- | Picture's width in pixels.
[pictureWidth] :: PictureData -> !Word32
-- | Picture's height in pixels.
[pictureHeight] :: PictureData -> !Word32
-- | Picture's color depth in bits-per-pixel.
[pictureDepth] :: PictureData -> !Word32
-- | For indexed palettes (like GIF), picture's number of colors (the
-- number of palette entries), or 0 for non-indexed (i.e. 2 ^ depth).
[pictureColors] :: PictureData -> !Word32
-- | Binary picture data.
[pictureData] :: PictureData -> !ByteString
-- | Delete all “Vorbis comment” metadata blocks.
wipeVorbisComment :: FlacMeta ()
-- | Delete all “Application” metadata blocks.
wipeApplications :: FlacMeta ()
-- | Delete all “Seek table” metadata blocks.
wipeSeekTable :: FlacMeta ()
-- | Delete all “CUE sheet” metadata blocks.
wipeCueSheets :: FlacMeta ()
-- | Delete all “Picture” metadata blocks.
wipePictures :: FlacMeta ()
-- | Enumeration of all known metadata blocks.
data MetadataType
-- | Stream info block (general data like sample rate)
StreamInfoBlock :: MetadataType
-- | Padding block
PaddingBlock :: MetadataType
-- | Application block
ApplicationBlock :: MetadataType
-- | Seek table block
SeekTableBlock :: MetadataType
-- | Vorbis comment block, a.k.a. FLAC tags
VorbisCommentBlock :: MetadataType
-- | Cue sheet block
CueSheetBlock :: MetadataType
-- | Picture block
PictureBlock :: MetadataType
-- | Undefined block
UndefinedBlock :: MetadataType
-- | Return list of all MetadataTypes of metadata blocks detected in
-- order.
getMetaChain :: FlacMeta (NonEmpty MetadataType)
-- | Return True if actions in current FlacMeta context have
-- modified FLAC metadata. If so, the FLAC file will be updated to
-- reflect these changes on the way out from the FlacMeta monad.
isMetaChainModified :: FlacMeta Bool
instance GHC.Enum.Enum Codec.Audio.FLAC.Metadata.VorbisField
instance GHC.Enum.Bounded Codec.Audio.FLAC.Metadata.VorbisField
instance GHC.Classes.Ord Codec.Audio.FLAC.Metadata.VorbisField
instance GHC.Classes.Eq Codec.Audio.FLAC.Metadata.VorbisField
instance GHC.Read.Read Codec.Audio.FLAC.Metadata.VorbisField
instance GHC.Show.Show Codec.Audio.FLAC.Metadata.VorbisField
instance GHC.Classes.Ord Codec.Audio.FLAC.Metadata.MetaSettings
instance GHC.Classes.Eq Codec.Audio.FLAC.Metadata.MetaSettings
instance GHC.Read.Read Codec.Audio.FLAC.Metadata.MetaSettings
instance GHC.Show.Show Codec.Audio.FLAC.Metadata.MetaSettings
instance Control.Monad.Catch.MonadMask Codec.Audio.FLAC.Metadata.FlacMeta
instance Control.Monad.Catch.MonadCatch Codec.Audio.FLAC.Metadata.FlacMeta
instance Control.Monad.Catch.MonadThrow Codec.Audio.FLAC.Metadata.FlacMeta
instance Control.Monad.IO.Class.MonadIO Codec.Audio.FLAC.Metadata.FlacMeta
instance GHC.Base.Monad Codec.Audio.FLAC.Metadata.FlacMeta
instance GHC.Base.Applicative Codec.Audio.FLAC.Metadata.FlacMeta
instance GHC.Base.Functor Codec.Audio.FLAC.Metadata.FlacMeta
instance Data.Default.Class.Default Codec.Audio.FLAC.Metadata.MetaSettings
instance Codec.Audio.FLAC.Metadata.MetaValue Codec.Audio.FLAC.Metadata.MinBlockSize
instance Codec.Audio.FLAC.Metadata.MetaValue Codec.Audio.FLAC.Metadata.MaxBlockSize
instance Codec.Audio.FLAC.Metadata.MetaValue Codec.Audio.FLAC.Metadata.MinFrameSize
instance Codec.Audio.FLAC.Metadata.MetaValue Codec.Audio.FLAC.Metadata.MaxFrameSize
instance Codec.Audio.FLAC.Metadata.MetaValue Codec.Audio.FLAC.Metadata.SampleRate
instance Codec.Audio.FLAC.Metadata.MetaValue Codec.Audio.FLAC.Metadata.Channels
instance Codec.Audio.FLAC.Metadata.MetaValue Codec.Audio.FLAC.Metadata.ChannelMask
instance Codec.Audio.FLAC.Metadata.MetaValue Codec.Audio.FLAC.Metadata.BitsPerSample
instance Codec.Audio.FLAC.Metadata.MetaValue Codec.Audio.FLAC.Metadata.TotalSamples
instance Codec.Audio.FLAC.Metadata.MetaValue Codec.Audio.FLAC.Metadata.FileSize
instance Codec.Audio.FLAC.Metadata.MetaValue Codec.Audio.FLAC.Metadata.BitRate
instance Codec.Audio.FLAC.Metadata.MetaValue Codec.Audio.FLAC.Metadata.MD5Sum
instance Codec.Audio.FLAC.Metadata.MetaValue Codec.Audio.FLAC.Metadata.Duration
instance Codec.Audio.FLAC.Metadata.MetaValue Codec.Audio.FLAC.Metadata.Application
instance Codec.Audio.FLAC.Metadata.MetaValue Codec.Audio.FLAC.Metadata.SeekTable
instance Codec.Audio.FLAC.Metadata.MetaValue Codec.Audio.FLAC.Metadata.VorbisVendor
instance Codec.Audio.FLAC.Metadata.MetaValue Codec.Audio.FLAC.Metadata.VorbisComment
instance Codec.Audio.FLAC.Metadata.MetaValue Codec.Audio.FLAC.Metadata.CueSheet
instance Codec.Audio.FLAC.Metadata.MetaValue Codec.Audio.FLAC.Metadata.Picture
-- | The module contains a Haskell interface to FLAC stream decoder.
--
-- How to use this module
--
-- Just call the decodeFlac function with DecoderSettings,
-- input and output file names. The decodeFlac function can
-- produce 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 pure C
-- implementation. Decoding speed is equal to that of flac
-- command line tool. Memory consumption is minimal and remains constant
-- regardless of size of file to decode.
module Codec.Audio.FLAC.StreamDecoder
-- | Parameters of stream decoder.
data DecoderSettings
DecoderSettings :: !Bool -> !WaveFormat -> DecoderSettings
-- | If True, the decoder will compute the MD5 signature of the
-- unencoded audio data while decoding and compare it to the signature
-- from the STREAMINFO block. Default value: False.
[decoderMd5Checking] :: DecoderSettings -> !Bool
-- | This specifies WAVE format in which to save the decoded file. You can
-- choose between WaveVanilla and WaveRF64; choose the
-- latter if uncompressed file is expected to be longer than 4 Gb.
-- Default value: WaveVanilla.
[decoderWaveFormat] :: DecoderSettings -> !WaveFormat
-- | Exception that is thrown when decoding fails for some reason.
data DecoderException
-- | Decoder initialization failed.
DecoderInitFailed :: DecoderInitStatus -> DecoderException
-- | Decoder failed.
DecoderFailed :: DecoderState -> DecoderException
-- | Status of decoder initialization process.
data DecoderInitStatus
-- | Initialization was successful.
DecoderInitStatusOK :: DecoderInitStatus
-- | The library was not compiled with support for the given container
-- format.
DecoderInitStatusUnsupportedContainer :: DecoderInitStatus
-- | A required callback was not supplied.
DecoderInitStatusInvalidCallbacks :: DecoderInitStatus
-- | An error occurred allocating memory.
DecoderInitStatusMemoryAllocationError :: DecoderInitStatus
-- | fopen() failed.
DecoderInitStatusErrorOpeningFile :: DecoderInitStatus
-- | Initialization was attempted on already initialized decoder.
DecoderInitStatusAlreadyInitialized :: DecoderInitStatus
-- | Enumeration of decoder states.
data DecoderState
-- | The decoder is ready to search for metadata.
DecoderStateSearchForMetadata :: DecoderState
-- | The decoder is ready to or is in the process of reading metadata.
DecoderStateReadMetadata :: DecoderState
-- | The decoder is ready to or is in the process of searching for the
-- frame sync code.
DecoderStateSearchForFrameSync :: DecoderState
-- | The decoder is ready to or is in the process of reading a frame.
DecoderStateReadFrame :: DecoderState
-- | The decoder has reached the end of the stream.
DecoderStateEndOfStream :: DecoderState
-- | An error occurred in the underlying Ogg layer.
DecoderStateOggError :: DecoderState
-- | An error occurred while seeking. The decoder must be flushed or reset
-- before decoding can continue.
DecoderStateSeekError :: DecoderState
-- | The decoder was aborted by the read callback.
DecoderStateAborted :: DecoderState
-- | An error occurred allocating memory. The decoder is in an invalid
-- state and can no longer be used.
DecoderStateMemoryAllocationError :: DecoderState
-- | The decoder is in the uninitialized state.
DecoderStateUnititialized :: DecoderState
-- | Decode a FLAC file to WAVE.
--
-- DecoderException is thrown when underlying FLAC decoder reports
-- a problem.
decodeFlac :: MonadIO m => DecoderSettings -> FilePath -> FilePath -> m ()
instance GHC.Classes.Ord Codec.Audio.FLAC.StreamDecoder.DecoderSettings
instance GHC.Classes.Eq Codec.Audio.FLAC.StreamDecoder.DecoderSettings
instance GHC.Read.Read Codec.Audio.FLAC.StreamDecoder.DecoderSettings
instance GHC.Show.Show Codec.Audio.FLAC.StreamDecoder.DecoderSettings
instance Data.Default.Class.Default Codec.Audio.FLAC.StreamDecoder.DecoderSettings