cl qoa

1.0.0

An implementation of the Quite Okay Audio format.

About cl-qoa

This is an implementation of the Quite OK Audio format, modelled after the reference implementation.

How To

First, raw-decode a file from any storage supported by binary-structures, like a stream, file, or raw pointer.

(org.shirakumo.qoa:read-file file)

Now with the file in memory, you can decode it to a sample buffer:

(org.shirakumo.qoa:decode-file *)

It will return the raw signed-byte 16 buffer. You can also use decode-to-buffer to decode the audio piecemeal. To query the file attributes, you can use channels and samplerate.

Similarly, you can encode a sample buffer into a QOA file.

(org.shirakumo.qoa:encode-from-buffer samples)

Which can then be written out to any supported storage backend again.

(org.shirakumo.qoa:write-file * file)

In both cases, samples are stored interleaved. You can get the channel order for each particular count of channels with the channel-layout function.

If you just need to convert a WAV file, you can use the convert-wav function. It requires the samples to be in SINT16 format and will error on any other format. If you need to convert samplerates or sample format, you can use a tool like ffmpeg to pre-convert it.

(let ((path "myfile.wav"))
  (uiop:run-program (list "ffmpeg" "-i" (uiop:native-namestring path)
                          "-c:a" "pcm_s16le" "-y" (uiop:native-namestring path)))
  (org.shirakumo.qoa:convert-wav path))

System Information

Version: 1.0.0

Dependencies:

Author: Yukari Hafner

License: zlib

Homepage: https://shinmera.github.io/cl-qoa/

Bug Tracker: https://github.com/shinmera/cl-qoa/issues

Sources: https://github.com/shinmera/cl-qoa.git

Definition Index

ORG.SHIRAKUMO.QOA

No documentation provided.

EXTERNAL STRUCTURE

FILE

Source

Representation of an encoded QOA file.

QOA files contain PCM-encoded audio with a 16-bit signed integer
representation. Each file is composed out of multiple frames of
encoded data, with possibly variable numbers of channels and
samplerates per frame, though this is not typically the case.

See OCTET-SIZE
See FRAMES
See SAMPLERATE
See CHANNELS
See READ-FILE
See WRITE-FILE
See ENCODE-FILE
See ENCODE-FROM-BUFFER
See DECODE-FRAME
See DECODE-TO-BUFFER

EXTERNAL STRUCTURE

FRAME

Source

Representation of an audio frame as part of a QOA file.

A frame contains the encoding of the sample data, a LMS state buffer,
and an array of encoded audio slices.

See OCTET-SIZE
See SAMPLERATE
See CHANNELS
See DECODE-FRAME
See FILE (type)

EXTERNAL FUNCTION

CHANNEL-LAYOUT

COUNT

Source

Returns the layout of the channels within the packed sample buffer for a given channel count.

The following speaker types are provided:
  :center :left :right :left-front :right-front :subwoofer :left-rear
  :right-rear :left-side :right-side

EXTERNAL FUNCTION

CONVERT-WAV

IN
&KEY
OUT
IF-EXISTS

Source

Converts a wav file to a QOA file.

IN should be the path to a RIFF WAVE file with sint16_le encoded audio
samples to convert. OUT should be the path to which the QOA file
should be written.

Returns OUT.

If the source file is not a wave file or does not contain the correct
sample format, an error is signalled.

See ENCODE-FILE

EXTERNAL FUNCTION

DECODE-FILE

FILE
&REST
ARGS

Source

Decodes a QOA file to a sample buffer.

Returns three values:
  The sample buffer,
  The number of channels of audio,
  The samplerate of the audio.

This assumes that the entire file has a constant channel count and
samplerate.

See DECODE-TO-BUFFER
See DECODE-FILE

EXTERNAL FUNCTION

DECODE-FRAME

FRAME
SAMPLES
START
END

Source

Decodes a single audio frame to a raw sample buffer.

FRAME must be a FRAME instance, SAMPLES must be a
(SIMPLE-ARRAY (SIGNED-BYTE 16) (*)) and START and END must be indices
into the SAMPLES array denoting the region to fill.

Returns the index into the SAMPLES array up to which samples were
written, same as CL:READ-SEQUENCE.

If the sample buffer is not big enough to contain the entire frame,
START is returned.

See FRAME (type)

EXTERNAL FUNCTION

DECODE-TO-BUFFER

FILE
SAMPLES
&KEY
FRAME-START
START
END

Source

Decodes the entire FILE to a raw sample buffer.

FILE must be a FILE, SAMPLES must be a
(SIMPLE-ARRAY (SIGNED-BYTE 16) (*)) and START and END must be indices
into the SAMPLES array denoting the region to fill. FRAME-START can
designate the first frame of the file that should be decoded.

Returns the index into the SAMPLES array up to which samples were
written, same as CL:READ-SEQUENCE, as well as the index of the next
frame to be decoded.

This assumes that the entire file has a constant channel count and
samplerate.

See FILE (type)
See DECODE-FRAME

EXTERNAL FUNCTION

ENCODE-FILE

SAMPLES
OUTPUT
&REST
ARGS
&KEY
CHANNELS
SAMPLERATE
&ALLOW-OTHER-KEYS

Source

Encode a sample buffer and write it to storage immediately.

OUTPUT may be a storage backend supported by WRITE-FILE, or the symbol
VECTOR, in which case a vector of sufficient size is allocated for you
and returned.

See FILE (type)
See ENCODE-FROM-BUFFER
See WRITE-FILE

EXTERNAL FUNCTION

ENCODE-FROM-BUFFER

SAMPLES
&KEY
CHANNELS
SAMPLERATE

Source

Creates a FILE from a buffer of audio samples.

SAMPLES must be a (SIMPLE-ARRAY (SIGNED-BYTE 16) (*)), CHANNELS should
be within [1,8], and SAMPLERATE within [1,16777215].

Returns a fresh FILE instance.

See FILE (type)

EXTERNAL FUNCTION

READ-FILE

STORAGE
&REST
ARGS

Source

Reads a QOA file from its binary representation.

The STORAGE may be any storage backend supported by binary-structures.

Returns a fresh FILE instance as well as the index at which reading
stopped, if applicable.

See FILE (type)

EXTERNAL FUNCTION

WRITE-FILE

VALUE
STORAGE
&REST
ARGS

Source

Writes a QOA file to its binary representation.

The STORAGE may be any storage backend supported by binary-structures.
It must have enough space available to contain the entire file. To
check this beforehand, you can call OCTET-SIZE.

Returns the index at which writing stopped.

See FILE (type)
See OCTET-SIZE

EXTERNAL GENERIC-FUNCTION

CHANNELS

FRAME

Returns the number of channels of the file or frame.

See FILE (type)
See FRAME (type)

EXTERNAL GENERIC-FUNCTION

FRAMES

FILE

Returns the vector of FRAME instances of the FILE

See FILE (type)
See FRAME (type)

EXTERNAL GENERIC-FUNCTION

OCTET-SIZE

FRAME

Returns the octet-size of the QOA file or frame if it were written out.

See FILE (type)
See FRAME (type)

EXTERNAL GENERIC-FUNCTION

SAMPLERATE

FRAME

Returns the samplerate of the file or frame in Herz.

See FILE (type)
See FRAME (type)