flac-0.2.1: README.md
# FLAC for Haskell
[](http://opensource.org/licenses/BSD-3-Clause)
[](https://hackage.haskell.org/package/flac)
[](http://stackage.org/nightly/package/flac)
[](http://stackage.org/lts/package/flac)
* [Aims of the project](#aims-of-the-project)
* [Motivation](#motivation)
* [Provided functionality](#provided-functionality)
* [Limitations](#limitations)
* [Quick start](#quick-start)
* [Related packages](#related-packages)
* [Contribution](#contribution)
* [License](#license)
This is a complete high-level Haskell binding to
[libFLAC](https://xiph.org/flac/)—reference FLAC implementation.
> As the maintainer of the C FLAC code base, I must say I'm impressed. Quite
> honestly, I think the C API is horrible.
>
> —[Erik de Castro Lopo](https://www.reddit.com/r/haskell/comments/5lyk70/announcing_flac_a_complete_highlevel_binding_to/dc00yb7/)
## Aims of the project
These are the goals of the project:
* Be a complete interface for FLAC file manipulation in Haskell.
* Be as efficient as the underlying C implementation.
* Provide a safe API using type system to kindly guard against bad things,
but not too much so as to remain beginner-friendly and simple.
## Motivation
FLAC is awesome and Haskell is awesome, surely there should be a safe
Haskell API to the fast libFLAC library!
Seriously though, we have
[`htaglib`](https://hackage.haskell.org/package/htaglib) to work with audio
metadata, but it does not support FLAC-specific thing I would like to
manipulate. We have
[`hsndfile`](https://hackage.haskell.org/package/hsndfile), but I don't
really want to read FLAC data into a buffer or Haskell `Vector`. How simple
is it (if possible) to decode a FLAC file using that library? How simple is
it to figure out where to begin with such a task? With `flac` it is one line
of code.
## Provided functionality
`flac` can work with:
* Metadata—full support for reading/writing/deleting of all audio
parameters, application data, seek tables, vorbis comments of all sorts,
CUE sheets, and even pictures.
* Stream decoder—simple interface for decoding to WAVE and RF64.
* Stream encoder—a lot of options to tweak, everything that libFLAC
supports.
## Limitations
Right now there are three main limitations:
* No Ogg FLAC support, and I do not plan to add it; I'll accept a PR adding
support for Ogg FLAC.
* It's not possible to use custom callbacks for printing decoding/encoding
progress in real-time.
* Only works on little-endian architectures so far; I'll accept a PR lifting
this limitation.
## Quick start
The best way to start using `flac` is to take a look at [the
Haddocks](https://hackage.haskell.org/package/flac). Encoding and decoding
should be simple to understand, for metadata there are examples in the docs.
Feel free to ask me a question if you get stuck with something.
## Related packages
The following packages are designed to be used with `flac`:
* [`flac-picture`](https://hackage.haskell.org/package/flac-picture)—add
pictures to FLAC metadata easier.
## Contribution
Please direct all issues, bugs, and questions to [the GitHub issue tracker
for this project](https://github.com/mrkkrp/flac/issues).
Pull requests are also welcome.
## License
Copyright © 2016–present Mark Karpov
Distributed under BSD 3 clause license.