The cl-flac Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-flac Reference Manual

This is the cl-flac Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 03:45:05 2022 GMT+0.

Table of Contents


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.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-flac

Bindings to libflac, a simple FLAC decoding library

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

Version

1.0.0

Dependencies
  • cffi (system).
  • trivial-features (system).
  • trivial-garbage (system).
  • documentation-utils (system).
Source

cl-flac.asd.

Child Components

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

3.1.1 cl-flac/cl-flac.asd

Source

cl-flac.asd.

Parent Component

cl-flac (system).

ASDF Systems

cl-flac.


3.1.2 cl-flac/package.lisp

Source

cl-flac.asd.

Parent Component

cl-flac (system).

Packages

3.1.3 cl-flac/low-level.lisp

Dependency

package.lisp (file).

Source

cl-flac.asd.

Parent Component

cl-flac (system).

Public Interface
Internals

3.1.4 cl-flac/wrapper.lisp

Dependency

low-level.lisp (file).

Source

cl-flac.asd.

Parent Component

cl-flac (system).

Public Interface
Internals

Previous: , Up: Lisp   [Contents][Index]

3.1.5 cl-flac/documentation.lisp

Dependency

wrapper.lisp (file).

Source

cl-flac.asd.

Parent Component

cl-flac (system).


4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 cl-flac-cffi

Source

package.lisp.

Nickname

org.shirakumo.fraf.flac.cffi

Use List
  • cffi.
  • common-lisp.
Public Interface
Internals

Previous: , Up: Packages   [Contents][Index]

4.2 cl-flac

Source

package.lisp.

Nickname

org.shirakumo.fraf.flac

Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


5.1.1 Ordinary functions

Function: bits-per-sample (file)
Package

cl-flac-cffi.

Source

low-level.lisp.

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.

Function: channels (file)
Package

cl-flac-cffi.

Source

low-level.lisp.

Function: channels (file0)

Returns the number of channels that the file encodes.

See FILE

Package

cl-flac.

Source

wrapper.lisp.

Function: close-file (file)

Explicitly close the file.

Note that this will render the instance useless.

See FILE

Package

cl-flac.

Source

wrapper.lisp.

Function: frame-count (file)
Package

cl-flac-cffi.

Source

low-level.lisp.

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.

Function: free-file (file)
Package

cl-flac-cffi.

Source

low-level.lisp.

Reader: handle (instance)

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

See FILE

Package

cl-flac.

Source

wrapper.lisp.

Target Slot

handle.

Writer: (setf handle) (instance)
Package

cl-flac.

Source

wrapper.lisp.

Target Slot

handle.

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.

Function: open-file (path file)
Package

cl-flac-cffi.

Source

low-level.lisp.

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.

Function: read-f32 (data samples file)
Package

cl-flac-cffi.

Source

low-level.lisp.

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.

Function: read-s16 (data samples file)
Package

cl-flac-cffi.

Source

low-level.lisp.

Function: read-s32 (data samples file)
Package

cl-flac-cffi.

Source

low-level.lisp.

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.

Function: sample-count (file)
Package

cl-flac-cffi.

Source

low-level.lisp.

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.

Function: sample-rate (file)
Package

cl-flac-cffi.

Source

low-level.lisp.

Function: samplerate (file0)

Returns the samplerate of the file in Hertz.

See FILE

Package

cl-flac.

Source

wrapper.lisp.

Function: seek (sample file)
Package

cl-flac-cffi.

Source

low-level.lisp.

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.

Function: strerror (error)
Package

cl-flac-cffi.

Source

low-level.lisp.


5.1.2 Standalone methods

Method: print-object ((file file) stream)
Source

wrapper.lisp.


5.1.3 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.

Direct superclasses

structure-object.

Direct methods

print-object.

Direct slots
Slot: path
Initform

pathname

Readers

path.

Writers

This slot is read-only.

Slot: handle
Initform

cffi-sys:foreign-pointer

Readers

handle.

Writers

(setf handle).


5.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.1 Special variables

Special Variable: *here*
Package

cl-flac-cffi.

Source

low-level.lisp.

Special Variable: *static*
Package

cl-flac-cffi.

Source

low-level.lisp.


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.

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.


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.3 Ordinary functions

Function: %make-file (path handle)
Package

cl-flac.

Source

wrapper.lisp.

Function: copy-file (instance)
Package

cl-flac.

Source

wrapper.lisp.

Function: file-p (object)
Package

cl-flac.

Source

wrapper.lisp.

Reader: path (instance)

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

See FILE

Package

cl-flac.

Source

wrapper.lisp.

Target Slot

path.


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.4 Generic functions

Generic Reader: code (condition)

Returns the error code encapsulated in the condition.

See FLAC-ERROR

Package

cl-flac.

Methods
Reader Method: code ((condition flac-error))
Source

wrapper.lisp.

Target Slot

code.

Generic Writer: (setf code) (condition)
Package

cl-flac.

Methods
Writer Method: (setf code) ((condition flac-error))
Source

wrapper.lisp.

Target Slot

code.


Previous: , Up: Internals   [Contents][Index]

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.

Direct superclasses

error.

Direct methods
Direct slots
Slot: code
Initargs

:code

Readers

code.

Writers

(setf code).


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %   (  
B   C   D   F   G   H   M   O   P   R   S   W  
Index Entry  Section

%
%make-file: Private ordinary functions

(
(setf code): Private generic functions
(setf code): Private generic functions
(setf handle): Public ordinary functions

B
bits-per-sample: Public ordinary functions
bits-per-sample: Public ordinary functions

C
channels: Public ordinary functions
channels: Public ordinary functions
close-file: Public ordinary functions
code: Private generic functions
code: Private generic functions
copy-file: Private ordinary functions

D
define-cfun-wrapper: Private macros

F
file-p: Private ordinary functions
frame-count: Public ordinary functions
frame-count: Public ordinary functions
free-file: Public ordinary functions
Function, %make-file: Private ordinary functions
Function, (setf handle): Public ordinary functions
Function, bits-per-sample: Public ordinary functions
Function, bits-per-sample: Public ordinary functions
Function, channels: Public ordinary functions
Function, channels: Public ordinary functions
Function, close-file: Public ordinary functions
Function, copy-file: Private ordinary functions
Function, file-p: Private ordinary functions
Function, frame-count: Public ordinary functions
Function, frame-count: Public ordinary functions
Function, free-file: Public ordinary functions
Function, handle: Public ordinary functions
Function, make-file: Public ordinary functions
Function, open-file: Public ordinary functions
Function, path: Private ordinary functions
Function, read-directly: Public ordinary functions
Function, read-f32: Public ordinary functions
Function, read-into-vector: Public ordinary functions
Function, read-s16: Public ordinary functions
Function, read-s32: Public ordinary functions
Function, read-to-vector: Public ordinary functions
Function, sample-count: Public ordinary functions
Function, sample-count: Public ordinary functions
Function, sample-rate: Public ordinary functions
Function, samplerate: Public ordinary functions
Function, seek: Public ordinary functions
Function, seek: Public ordinary functions
Function, strerror: Public ordinary functions

G
Generic Function, (setf code): Private generic functions
Generic Function, code: Private generic functions

H
handle: Public ordinary functions

M
Macro, define-cfun-wrapper: Private macros
Macro, with-error: Private macros
make-file: Public ordinary functions
Method, (setf code): Private generic functions
Method, code: Private generic functions
Method, print-object: Public standalone methods

O
open-file: Public ordinary functions

P
path: Private ordinary functions
print-object: Public standalone methods

R
read-directly: Public ordinary functions
read-f32: Public ordinary functions
read-into-vector: Public ordinary functions
read-s16: Public ordinary functions
read-s32: Public ordinary functions
read-to-vector: Public ordinary functions

S
sample-count: Public ordinary functions
sample-count: Public ordinary functions
sample-rate: Public ordinary functions
samplerate: Public ordinary functions
seek: Public ordinary functions
seek: Public ordinary functions
strerror: Public ordinary functions

W
with-error: Private macros

Jump to:   %   (  
B   C   D   F   G   H   M   O   P   R   S   W