audio.codec
Open and save a sound file without naming its format.
import audio.codec
This package is the one call that does not care what format a file is in. Open reads the first bytes, works out the format and hands back a clip; Save looks at the extension and writes the right thing. Probe and ProbeFile do the same for a header alone.
It sits in its own package for a plain reason: audio cannot import the format packages, because they import it. So the sniffing lives in audio, where it needs nothing, and the dispatch lives here, where it can reach every codec.
Things to know
- Knowing a format and being able to read it are different things.
audio.DetectFormatnames ten formats;CanDecodetells you which of them this build actually carries, andFormatslists them. - Today that list is WAV, AIFF and au. The rest of the family is being written, and nothing here changes when they land.
Savereturns false for an extension it cannot write, rather than writing the wrong format.- Free the clip with
audio.Freeand any buffer withcompress.BufFree.
Saving and opening by file name
codec.Save picks the format from the file extension, so the same call writes a .wav, .aiff, .au or .flac file. It returns false for a format it cannot write, such as MP3. CanEncode and CanDecode tell you in advance.
import audio
import audio.codec
import filepath
import mem
import os
func main:
mut c := audio.New(22050, 2, 64)
audio.SetSample(c, 5, 0, 0.5)
audio.SetSample(c, 5, 1, -0.25)
path := filepath.Join(os.TempDir(), "salam_guide_codec.wav")
defer mem.Free(path as void*)
println codec.CanEncode(audio.FormatWAV), codec.Save(c, path)
mut ok := false
info := codec.ProbeFile(path, ok)
println ok, audio.FormatName(info.format), info.frames, info.bits, info.lossless
mut open_ok := false
mut back := codec.Open(path, open_ok)
println open_ok, back.rate, back.channels
println audio.Sample(back, 5, 0), audio.Sample(back, 5, 1)
audio.Free(c)
audio.Free(back)
endProbeFile reads the header only and reports the format name, length, depth and whether the format is lossless. Open then decodes the file, whatever format it turns out to be, since it looks at the contents and not at the name.
Encoding and decoding in memory
Without a file, Encode returns a byte buffer in the format you name, and Decode turns bytes back into a clip. The 32 frame mono clip becomes 108 bytes: a 44 byte header and 64 bytes of 16 bit samples. audio.DetectFormat names the format from the bytes alone.
import audio
import audio.codec
import compress
func main:
mut c := audio.New(8000, 1, 32)
audio.SetSample(c, 3, 0, 0.5)
mut buf := codec.Encode(c, audio.FormatWAV)
println compress.BufLen(buf)
println audio.FormatName(audio.DetectFormat(buf.data, buf.len))
mut ok := false
mut back := codec.Decode(buf.data, buf.len, ok)
println ok, back.frames, audio.Sample(back, 3, 0)
mut junk := compress.NewByteBuf()
mut i := 0
until i < 16:
compress.BufPush(junk, i)
i++
end
mut bad := false
codec.Decode(junk.data, junk.len, bad)
println bad
compress.BufFree(buf)
compress.BufFree(junk)
audio.Free(c)
audio.Free(back)
endBytes that are not audio do not crash anything: Decode sets its flag to false and returns an empty clip. Always check the flag before using the result, and free the buffers you were given.
Functions
CanDecode
func CanDecode(format: int): boolimport audio
import audio.codec
import compress
import filepath
import mem
import os
func main:
println codec.CanDecode(audio.FormatWAV), codec.CanEncode(audio.FormatWAV)
println codec.CanDecode(audio.FormatMP3), codec.CanEncode(audio.FormatFLAC)
println codec.Formats().Len(), codec.Formats().Get(0) == audio.FormatWAV
mut c := audio.New(22050, 2, 64)
audio.SetSample(c, 5, 0, 0.5)
audio.SetSample(c, 5, 1, -0.25)
path := filepath.Join(os.TempDir(), "salam_codec_open.wav")
defer mem.Free(path as void*)
println codec.Save(c, path)
mut ok := false
mut back := codec.Open(path, ok)
println ok, back.frames, back.channels, back.rate, back.bits
println audio.Sample(back, 5, 0), audio.Sample(back, 5, 1)
mut pok := false
info := codec.ProbeFile(path, pok)
println pok, audio.FormatName(info.format), info.frames, info.bits, info.lossless
mut buf := codec.Encode(c, audio.FormatWAV)
println compress.BufLen(buf) == 44 + 64 * 2 * 2
mut mok := false
mut mem_back := codec.Decode(buf.data, buf.len, mok)
println mok, mem_back.frames
mut iok := false
mem_info := codec.Probe(buf.data, buf.len, iok)
println iok, mem_info.channels
mp3 := filepath.Join(os.TempDir(), "salam_codec_open.mp3")
defer mem.Free(mp3 as void*)
println codec.Save(c, mp3)
println compress.BufLen(codec.Encode(c, audio.FormatMP3))
mut bad := false
mut junk := compress.NewByteBuf()
mut i := 0
until i < 16:
compress.BufPush(junk, i)
i++
end
codec.Decode(junk.data, junk.len, bad)
println bad
mut gone := false
nope := filepath.Join(os.TempDir(), "salam_codec_nope.wav")
defer mem.Free(nope as void*)
codec.Open(nope, gone)
println gone
compress.BufFree(buf)
compress.BufFree(junk)
audio.Free(c)
audio.Free(back)
audio.Free(mem_back)
endCanEncode
func CanEncode(format: int): boolThe example for this item is shown with the ones above: codec-Open.salam
Formats
func Formats(): Vector<int>The example for this item is shown with the ones above: codec-Open.salam
Decode
func Decode(p: void*, n: int, ok &: bool): audio.ClipThe example for this item is shown with the ones above: codec-Open.salam
Probe
func Probe(p: void*, n: int, ok &: bool): audio.InfoThe example for this item is shown with the ones above: codec-Open.salam
Open
func Open(path: str, ok &: bool): audio.ClipThe example for this item is shown with the ones above: codec-Open.salam
ProbeFile
func ProbeFile(path: str, ok &: bool): audio.InfoThe example for this item is shown with the ones above: codec-Open.salam
Encode
func Encode(c: audio.Clip, format: int): compress.ByteBufThe example for this item is shown with the ones above: codec-Open.salam
Save
func Save(c: audio.Clip, path: str): boolThe example for this item is shown with the ones above: codec-Open.salam