Copyright | © 2016–2017 Mark Karpov |
---|---|
License | BSD 3 clause |
Maintainer | Mark Karpov <markkarpov92@gmail.com> |
Stability | experimental |
Portability | portable |
Safe Haskell | None |
Language | Haskell2010 |
The module provides a complete high-level Haskell API to manipulate FLAC metadata.
How to use this module
Just like the 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 a 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
=->
)
metadata attribute by setting it to VorbisComment
Date
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 the level 2 metadata interface and it's not possible to choose other interface (such as level 0 and 1). However, this should not be of any concern to the end-user, as the level 2 supports more functionality than the other levels.
- data FlacMeta a
- data MetaSettings = MetaSettings {
- metaAutoVacuum :: !Bool
- metaSortPadding :: !Bool
- metaUsePadding :: !Bool
- metaPreserveFileStats :: !Bool
- data MetaException
- data MetaChainStatus
- = MetaChainStatusOK
- | MetaChainStatusIllegalInput
- | MetaChainStatusErrorOpeningFile
- | MetaChainStatusNotFlacFile
- | MetaChainStatusNotWritable
- | MetaChainStatusBadMetadata
- | MetaChainStatusReadError
- | MetaChainStatusSeekError
- | MetaChainStatusWriteError
- | MetaChainStatusRenameError
- | MetaChainStatusUnlinkError
- | MetaChainStatusMemoryAllocationError
- | MetaChainStatusInternalError
- | MetaChainStatusInvalidCallbacks
- | MetaChainStatusReadWriteMismatch
- | MetaChainStatusWrongWriteCall
- runFlacMeta :: MonadIO m => MetaSettings -> FilePath -> FlacMeta a -> m a
- class MetaValue a where
- type MetaType a :: *
- type MetaWritable a :: Constraint
- data MinBlockSize = MinBlockSize
- data MaxBlockSize = MaxBlockSize
- data MinFrameSize = MinFrameSize
- data MaxFrameSize = MaxFrameSize
- data SampleRate = SampleRate
- data Channels = Channels
- data ChannelMask = ChannelMask
- data BitsPerSample = BitsPerSample
- data TotalSamples = TotalSamples
- data FileSize = FileSize
- data BitRate = BitRate
- data MD5Sum = MD5Sum
- data Duration = Duration
- data Application = Application ApplicationId
- data ApplicationId
- mkApplicationId :: ByteString -> ApplicationId
- unApplicationId :: ApplicationId -> ByteString
- data SeekTable = SeekTable
- data SeekPoint = SeekPoint {}
- data VorbisVendor = VorbisVendor
- data VorbisComment = VorbisComment VorbisField
- data VorbisField
- data CueSheet = CueSheet
- data Picture = Picture PictureType
- data PictureType
- = PictureOther
- | PictureFileIconStandard
- | PictureFileIcon
- | PictureFrontCover
- | PictureBackCover
- | PictureLeafletPage
- | PictureMedia
- | PictureLeadArtist
- | PictureArtist
- | PictureConductor
- | PictureBand
- | PictureComposer
- | PictureLyricist
- | PictureRecordingLocation
- | PictureDuringRecording
- | PictureDuringPerformance
- | PictureVideoScreenCapture
- | PictureFish
- | PictureIllustration
- | PictureBandLogotype
- | PicturePublisherLogotype
- data PictureData = PictureData {
- pictureMimeType :: !Text
- pictureDescription :: !Text
- pictureWidth :: !Word32
- pictureHeight :: !Word32
- pictureDepth :: !Word32
- pictureColors :: !Word32
- pictureData :: !ByteString
- wipeVorbisComment :: FlacMeta ()
- wipeApplications :: FlacMeta ()
- wipeSeekTable :: FlacMeta ()
- wipeCueSheets :: FlacMeta ()
- wipePictures :: FlacMeta ()
- data MetadataType
- getMetaChain :: FlacMeta (NonEmpty MetadataType)
- isMetaChainModified :: FlacMeta Bool
Metadata manipulation API
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 MetaSettings Source #
Settings that control how metadata is written in FLAC file.
MetaSettings | |
|
data MetaException Source #
The exception that is thrown when manipulation of FLAC metadata fails for some reason.
MetaGeneralProblem MetaChainStatus | General failure, see the attached |
MetaInvalidSeekTable | Invalid seek table was passed to be written. |
MetaInvalidCueSheet Text | Invalid CUE sheet was passed to be written. The reason why the data was invalid is attached. |
MetaInvalidPicture Text | Invalid picture data was passed to be written. The reason why the data was invalid is attached. |
data MetaChainStatus Source #
Enumeration of meta chain statuses.
MetaChainStatusOK | The chain is in the normal OK state. |
MetaChainStatusIllegalInput | The data passed into a function violated the function's usage criteria. |
MetaChainStatusErrorOpeningFile | The chain could not open the target file. |
MetaChainStatusNotFlacFile | The chain could not find the FLAC signature at the start of the file. |
MetaChainStatusNotWritable | The chain tried to write to a file that was not writable. |
MetaChainStatusBadMetadata | The chain encountered input that does not conform to the FLAC metadata specification. |
MetaChainStatusReadError | The chain encountered an error while reading the FLAC file. |
MetaChainStatusSeekError | The chain encountered an error while seeking in the FLAC file. |
MetaChainStatusWriteError | The chain encountered an error while writing the FLAC file. |
MetaChainStatusRenameError | The chain encountered an error renaming the FLAC file. |
MetaChainStatusUnlinkError | The chain encountered an error removing the temporary file. |
MetaChainStatusMemoryAllocationError | Memory allocation failed. |
MetaChainStatusInternalError | The caller violated an assertion or an unexpected error occurred. |
MetaChainStatusInvalidCallbacks | One or more of the required callbacks was NULL. |
MetaChainStatusReadWriteMismatch | 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). |
MetaChainStatusWrongWriteCall | Should not ever happen when you use this binding. |
:: MonadIO m | |
=> MetaSettings | Settings to use |
-> FilePath | File to operate on |
-> FlacMeta a | Actions to perform |
-> m a | The result |
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 the metadata. Compose it from retrieve
and (
.=->
)
The action will throw UnicodeException
if the
text data like Vorbis Comment entries cannot be read as a UTF-8-encoded
value.
If a problem occurs, MetaException
is thrown with attached
MetaChainStatus
that should help investigating what went wrong.
Meta values
class MetaValue a where Source #
A class for the 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 the 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.
Type of data that corresponds to this metadata value. For example
SampleRate
is represented by Word32
value in this library, and so
.MetaType
SampleRate
= Word32
type MetaWritable a :: Constraint Source #
Associated type of the kind Constraint
that controls whether a
particular piece of metadata is writable or not.
retrieve :: a -> FlacMeta (MetaType a) Source #
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
.
(=->) :: MetaWritable a => a -> MetaType a -> FlacMeta () infix 1 Source #
Given a 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.
data MinBlockSize Source #
Minimal block size in samples used in the stream.
Read-only attribute represented as a Word32
.
data MaxBlockSize Source #
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 MinFrameSize Source #
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 MaxFrameSize Source #
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 SampleRate Source #
Sample rate in Hz.
Read-only attribute represented as a Word32
.
MetaValue SampleRate Source # | |
type MetaType SampleRate Source # | |
type MetaWritable SampleRate Source # | |
Number of channels. FLAC supports from 1 to 8 channels.
Read-only attribute represented as a Word32
.
data ChannelMask Source #
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
MetaValue ChannelMask Source # | |
type MetaType ChannelMask Source # | |
type MetaWritable ChannelMask Source # | |
data BitsPerSample Source #
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 TotalSamples Source #
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
.
File size in bytes.
Read-only attribute represented as a Natural
.
Bit rate in kilo-bits per second (kbps).
Read-only attribute represented as a Word32
.
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.
Duration in seconds.
Read-only attribute represented as a Double
.
data Application Source #
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
MetaValue Application Source # | |
type MetaType Application Source # | |
type MetaWritable Application Source # | |
data ApplicationId Source #
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 the mkApplicationId
smart constructor.
Extract the inner ByteString
with unApplicationId
.
mkApplicationId :: ByteString -> ApplicationId Source #
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.
unApplicationId :: ApplicationId -> ByteString Source #
Get ByteString
from ApplicationId
.
Seek table as a Vector
of SeekPoint
s. 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 the
MetaInvalidSeekTable
constructor.
Writable optional attribute represented as a
.Maybe
(Vector
SeekPoint
)
Single point in a seek table metadata block.
SeekPoint | |
|
data VorbisVendor Source #
Vorbis “vendor” comment. When “Vorbis Comment” metadata block is
present, the “vendor” entry is always in there, so when you delete it (by
), you really set it to an empty string
(which is enough to trigger auto vacuum feature if no other entries are
detected, see VorbisVendor
=->
Nothing
metaAutoVacuum
).
data VorbisComment Source #
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.
data VorbisField Source #
Enumeration of all supported filed names to index vorbis comment entries.
Title | Track/work name. |
Version | The version field may be used to differentiate multiple versions of the same track title in a single collection (e.g. remix info). |
Album | The collection name to which this track belongs. |
TrackNumber | The track number of this piece if part of a specific larger collection or album. |
TrackTotal | Total number of tracks in the collection this track belongs to. |
DiscNumber | Disc number in a multi-disc release. |
DiscTotal | Total number of discs in a multi-disc release. |
Artist | 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. |
Performer | 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 |
Copyright | Copyright attribution, e.g., “2001 Nobody's Band” or “1999 Jack Moffitt”. |
License | 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. |
Organization | Name of the organization producing the track (i.e. the “record label”). |
Description | A short text description of the contents. |
Genre | A short text indication of music genre. |
Date | Date the track was recorded, usually year. |
Location | Location where track was recorded. |
Contact | 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. |
ISRC | ISRC number for the track, see http://isrc.ifpi.org/en. |
Rating | Rating, usually mapped as 1–5 stars with actual values “20”, “40”, “60”, “80”, “100” stored. |
RGTrackPeak | Replay gain track peak, e.g. “0.99996948”. |
RGTrackGain | Replay gain track gain, e.g. “-7.89 dB”. |
RGAlbumPeak | Replay gain album peak, e.g. “0.99996948”. |
RGAlbumGain | Replay gain album gain, e.g. “-7.89 dB”. |
A CUE sheet stored in FLAC metadata. If you try to write an invalid CUE
sheet MetaException
will be raised with the 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 CueTrack
s.
Writable optional attribute represented as a
.Maybe
CueSheetData
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 PictureType Source #
Type of picture FLAC metadata can contain. There may be several metadata blocks containing pictures of different types.
PictureOther | Other |
PictureFileIconStandard | 32×32 pixels file icon (PNG only) |
PictureFileIcon | Other file icon |
PictureFrontCover | Cover (front) |
PictureBackCover | Cover (back) |
PictureLeafletPage | Leaflet page |
PictureMedia | Media (e.g. label side of CD) |
PictureLeadArtist | Lead artist/lead performer/soloist |
PictureArtist | Artist/performer |
PictureConductor | Conductor |
PictureBand | Band/orchestra |
PictureComposer | Composer |
PictureLyricist | Lyricist/text writer |
PictureRecordingLocation | Recording location |
PictureDuringRecording | During recording |
PictureDuringPerformance | During performance |
PictureVideoScreenCapture | Movie/video screen capture |
PictureFish | A bright coloured fish |
PictureIllustration | Illustration |
PictureBandLogotype | Band/artist logotype |
PicturePublisherLogotype | Publisher/studio logotype |
data PictureData Source #
Representation of picture contained in a FLAC metadata block.
PictureData | |
|
Extra functionality
wipeVorbisComment :: FlacMeta () Source #
Delete all “Vorbis comment” metadata blocks.
wipeApplications :: FlacMeta () Source #
Delete all “Application” metadata blocks.
wipeSeekTable :: FlacMeta () Source #
Delete all “Seek table” metadata blocks.
wipeCueSheets :: FlacMeta () Source #
Delete all “CUE sheet” metadata blocks.
wipePictures :: FlacMeta () Source #
Delete all “Picture” metadata blocks.
Debugging and testing
data MetadataType Source #
Enumeration of all known metadata blocks.
StreamInfoBlock | Stream info block (general data like sample rate) |
PaddingBlock | Padding block |
ApplicationBlock | Application block |
SeekTableBlock | Seek table block |
VorbisCommentBlock | Vorbis comment block, a.k.a. FLAC tags |
CueSheetBlock | Cue sheet block |
PictureBlock | Picture block |
UndefinedBlock | Undefined block |
getMetaChain :: FlacMeta (NonEmpty MetadataType) Source #
Return a list of all MetadataType
s of metadata blocks detected in
order.