The cl-flac Reference Manual

Table of Contents

The cl-flac Reference Manual

This is the cl-flac Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 03:46:23 2022 GMT+0.

1 Introduction

About cl-flac

This is a bindings library to libflac, a simple library for decoding FLAC files.

How To

Precompiled versions of the underlying library are included in this. If you want to build it manually however, refer to the libflac page.

Load the system through ASDF or Quicklisp:

(ql:quickload :cl-flac)

Create a new file object:

(defvar *file* (cl-flac:make-file #p"~/my-cool-music.flac"))

You can query the file information with samplerate, channels, sample-count, frame-count, and bits-per-sample.

Reading samples from the file happens with read-directly, read-into-vector, or read-to-vector. A basic playback loop could look like this:

(loop with buffer = (make-array 512 :element-type 'single-float)
      for samples = (cl-flac:read-into-vector *file* buffer)
      until (= 0 samples)
      do (process-buffer-somehow buffer))

When you're done with the file, you can either just let it be GCd or close it explicitly with close-file.

A complete test that allows you to play back a flac file is included in test.lisp

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 cl-flac

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://Shirakumo.github.io/cl-flac/

Source Control

(:git "https://github.com/shirakumo/cl-flac.git")

Bug Tracker

https://github.com/Shirakumo/cl-flac/issues

License

zlib

Description

Bindings to libflac, a simple FLAC decoding library

Version

1.0.0

Dependencies

• cffi
• trivial-features
• trivial-garbage
• documentation-utils

Source

cl-flac.asd (file)

Components

• package.lisp (file)
• low-level.lisp (file)
• wrapper.lisp (file)
• documentation.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 cl-flac.asd

Location

cl-flac.asd

Systems

cl-flac (system)

3.1.2 cl-flac/package.lisp

Parent

cl-flac (system)

Location

package.lisp

Packages

• cl-flac
• cl-flac-cffi

3.1.3 cl-flac/low-level.lisp

Dependency

package.lisp (file)

Parent

cl-flac (system)

Location

low-level.lisp

Exported Definitions

• bits-per-sample (function)
• channels (function)
• frame-count (function)
• free-file (function)
• open-file (function)
• read-f32 (function)
• read-s16 (function)
• read-s32 (function)
• sample-count (function)
• sample-rate (function)
• seek (function)
• strerror (function)

Internal Definitions

• *here* (special variable)
• *static* (special variable)

3.1.4 cl-flac/wrapper.lisp

Dependency

low-level.lisp (file)

Parent

cl-flac (system)

Location

wrapper.lisp

Exported Definitions

• bits-per-sample (function)
• channels (function)
• close-file (function)
• file (structure)
• frame-count (function)
• handle (function)
• (setf handle) (function)
• make-file (function)
• read-directly (function)
• read-into-vector (function)
• read-to-vector (function)
• sample-count (function)
• samplerate (function)
• seek (function)

Internal Definitions

• %make-file (function)
• code (method)
• (setf code) (method)
• copy-file (function)
• define-cfun-wrapper (macro)
• file-p (function)
• flac-error (condition)
• path (function)
• with-error (macro)

3.1.5 cl-flac/documentation.lisp

Dependency

wrapper.lisp (file)

Parent

cl-flac (system)

Location

documentation.lisp

4 Packages

Packages are listed by definition order.

4.1 cl-flac

Source

package.lisp (file)

Nickname

org.shirakumo.fraf.flac

Use List

common-lisp

Exported Definitions

• bits-per-sample (function)
• channels (function)
• close-file (function)
• file (structure)
• frame-count (function)
• handle (function)
• (setf handle) (function)
• make-file (function)
• read-directly (function)
• read-into-vector (function)
• read-to-vector (function)
• sample-count (function)
• samplerate (function)
• seek (function)

Internal Definitions

• %make-file (function)
• code (generic function)
• code (method)
• (setf code) (method)
• (setf code) (generic function)
• copy-file (function)
• define-cfun-wrapper (macro)
• file-p (function)
• flac-error (condition)
• path (function)
• with-error (macro)

4.2 cl-flac-cffi

Source

package.lisp (file)

Nickname

org.shirakumo.fraf.flac.cffi

Use List

• cffi
• common-lisp

Exported Definitions

• bits-per-sample (function)
• channels (function)
• frame-count (function)
• free-file (function)
• open-file (function)
• read-f32 (function)
• read-s16 (function)
• read-s32 (function)
• sample-count (function)
• sample-rate (function)
• seek (function)
• strerror (function)

Internal Definitions

• *here* (special variable)
• *static* (special variable)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Functions

Function: bits-per-sample FILE0

Returns the number of bits per sample as encoded in the file.

See FILE

Package

cl-flac

Source

wrapper.lisp (file)

Function: bits-per-sample FILE

Package

cl-flac-cffi

Source

low-level.lisp (file)

Function: channels FILE0

Returns the number of channels that the file encodes.

See FILE

Package

cl-flac

Source

wrapper.lisp (file)

Function: channels FILE

Package

cl-flac-cffi

Source

low-level.lisp (file)

Function: close-file FILE

Explicitly close the file.

Note that this will render the instance useless.

See FILE

Package

cl-flac

Source

wrapper.lisp (file)

Function: frame-count FILE0

Returns the number of frames stored in the file.

This is the number of samples divided by the number of channels, this giving the number of frames.

See SAMPLE-COUNT
See FILE

Package

cl-flac

Source

wrapper.lisp (file)

Function: frame-count FILE

Package

cl-flac-cffi

Source

low-level.lisp (file)

Function: free-file FILE

Package

cl-flac-cffi

Source

low-level.lisp (file)

Function: handle INSTANCE

Accessor to the handle for the underlying C data of the FLAC file.

See FILE

Package

cl-flac

Source

wrapper.lisp (file)

Writer

(setf handle) (function)

Function: (setf handle) VALUE INSTANCE

Package

cl-flac

Source

wrapper.lisp (file)

Reader

handle (function)

Function: make-file PATH

Create a new FLAC file from the given path.

If the path is not accessible, or the file is malformatted, an error is signalled.

See FILE

Package

cl-flac

Source

wrapper.lisp (file)

Function: open-file PATH FILE

Package

cl-flac-cffi

Source

low-level.lisp (file)

Function: read-directly FILE BUFFER-POINTER BUFFER-SIZE

Directly decode samples from the file into the buffer.

BUFFER-SIZE is in number of bytes, but must be aligned with the sample size. The buffer is filled with 32-bit float samples.

Returns the number of bytes successfully read. If this number is lower than the requested amount, the file has reached its end.

See FILE

Package

cl-flac

Source

wrapper.lisp (file)

Function: read-f32 DATA SAMPLES FILE

Package

cl-flac-cffi

Source

low-level.lisp (file)

Function: read-into-vector FILE VECTOR &optional START END

Decode samples into the vector.

The vector must have an element-type of either SINGLE-FLOAT, (SIGNED-BYTE 16), or (SIGNED-BYTE 32).

Returned is the number of samples that were actually decoded, as that might be lower than the requested amount if the file does not contain enough samples anymore.

See FILE

Package

cl-flac

Source

wrapper.lisp (file)

Function: read-s16 DATA SAMPLES FILE

Package

cl-flac-cffi

Source

low-level.lisp (file)

Function: read-s32 DATA SAMPLES FILE

Package

cl-flac-cffi

Source

low-level.lisp (file)

Function: read-to-vector FILE SAMPLES

Reads the given number of samples into a single-float vector.

Returns the vector and the number of samples that were actually decoded.

See READ-INTO-VECTOR
See FILE

Package

cl-flac

Source

wrapper.lisp (file)

Function: sample-count FILE0

Returns the total number of samples stored in the file.

See FRAME-COUNT
See FILE

Package

cl-flac

Source

wrapper.lisp (file)

Function: sample-count FILE

Package

cl-flac-cffi

Source

low-level.lisp (file)

Function: sample-rate FILE

Package

cl-flac-cffi

Source

low-level.lisp (file)

Function: samplerate FILE0

Returns the samplerate of the file in Hertz.

See FILE

Package

cl-flac

Source

wrapper.lisp (file)

Function: seek FILE FRAME

Seek to the requested frame.

Returns the file on success, signals a condition on failure.

See FILE

Package

cl-flac

Source

wrapper.lisp (file)

Function: seek SAMPLE FILE

Package

cl-flac-cffi

Source

low-level.lisp (file)

Function: strerror ERROR

Package

cl-flac-cffi

Source

low-level.lisp (file)

5.1.2 Structures

Structure: file ()

Container for the FLAC file.

Note that you do not need to explicitly close the file. It will automatically clean up when this instance is garbage collected.

See MAKE-FILE
See CLOSE-FILE
See HANDLE
See PATH
See CHANNELS
See SAMPLERATE
See BITS-PER-SAMPLE
See SAMPLE-COUNT
See FRAME-COUNT
See READ-DIRECTLY
See READ-INTO-VECTOR
See READ-TO-VECTOR
See SEEK

Package

cl-flac

Source

wrapper.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

print-object (method)

Direct slots

Slot: path

Initform

pathname

Readers

path (function)

Writers

(setf path) (function)

Slot: handle

Initform

cffi-sys:foreign-pointer

Readers

handle (function)

Writers

(setf handle) (function)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *here*

Package

cl-flac-cffi

Source

low-level.lisp (file)

Special Variable: *static*

Package

cl-flac-cffi

Source

low-level.lisp (file)

5.2.2 Macros

Macro: define-cfun-wrapper SLOT &optional CFUN

Defines a wrapper function that just returns what the inner C function returns.

Package

cl-flac

Source

wrapper.lisp (file)

Macro: with-error () &body BODY

Checks the returned code for error-ness and signals a condition if applicable.

See FLAC-ERROR

Package

cl-flac

Source

wrapper.lisp (file)

5.2.3 Functions

Function: %make-file PATH HANDLE

Package

cl-flac

Source

wrapper.lisp (file)

Function: copy-file INSTANCE

Package

cl-flac

Source

wrapper.lisp (file)

Function: file-p OBJECT

Package

cl-flac

Source

wrapper.lisp (file)

Function: path INSTANCE

Returns the path namestring that was used to read the file.

See FILE

Package

cl-flac

Source

wrapper.lisp (file)

5.2.4 Generic functions

Generic Function: code CONDITION

Returns the error code encapsulated in the condition.

See FLAC-ERROR

Package

cl-flac

Writer

(setf code) (generic function)

Methods

Method: code (CONDITION flac-error)

Source

wrapper.lisp (file)

Generic Function: (setf code) NEW-VALUE CONDITION

Package

cl-flac

Reader

code (generic function)

Methods

Method: (setf code) NEW-VALUE (CONDITION flac-error)

Source

wrapper.lisp (file)

5.2.5 Conditions

Condition: flac-error ()

This condition is signalled when an error in the underlying library is detected.

See CODE

Package

cl-flac

Source

wrapper.lisp (file)

Direct superclasses

error (condition)

Direct methods

• code (method)
• code (method)

Direct slots

Slot: code

Initargs

:code

Readers

code (generic function)

Writers

(setf code) (generic function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types