SAU parser, player, and WAV file writer. Main development repo. See "Wiki" for notes on versions and plans. https://sau.frama.io
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
Joel K. Pettersson afbee95d4f Rename '.w' to '.r' & add plain additive AM & FM. 3 weeks ago
devtests Rename '.w' to '.r' & add plain additive AM & FM. 3 weeks ago
doc Rename '.w' to '.r' & add plain additive AM & FM. 3 weeks ago
examples Rename '.w' to '.r' & add plain additive AM & FM. 3 weeks ago
man Add -v verbose option, rename version to -V. 3 weeks ago
notes Tweak timing modifier syntax, replace 's'. Refactor timing. 3 weeks ago
player Add -v verbose option, rename version to -V. 3 weeks ago
reader Rename '.w' to '.r' & add plain additive AM & FM. 3 weeks ago
renderer Rename '.w' to '.r' & add plain additive AM & FM. 3 weeks ago
.gitignore Rename project to 'saugns' from 'sgensys'. 3 weeks ago
COPYING Disable lexer testing. Clean-ups and portability fixes. 5 months ago
Makefile Support '-o -' audio to stdout with AU format header. 3 weeks ago
README.md Support '-o -' audio to stdout with AU format header. 3 weeks ago
arrtype.c Rename project to 'saugns' from 'sgensys'. 3 weeks ago
arrtype.h Rename project to 'saugns' from 'sgensys'. 3 weeks ago
common.c Add '--mono' and '--stdout' cli options. 3 weeks ago
common.h Add '--mono' and '--stdout' cli options. 3 weeks ago
help.c Add more math functions & some constants. 3 weeks ago
help.h Add more math functions & some constants. 3 weeks ago
math.c Add more math functions & some constants. 3 weeks ago
math.h Add more math functions & some constants. 3 weeks ago
mempool.c Rename project to 'saugns' from 'sgensys'. 3 weeks ago
mempool.h Rename project to 'saugns' from 'sgensys'. 3 weeks ago
program.h Rename '.w' to '.r' & add plain additive AM & FM. 3 weeks ago
ptrarr.c Rename project to 'saugns' from 'sgensys'. 3 weeks ago
ptrarr.h Rename project to 'saugns' from 'sgensys'. 3 weeks ago
ramp.c Rename project to 'saugns' from 'sgensys'. 3 weeks ago
ramp.h Rename project to 'saugns' from 'sgensys'. 3 weeks ago
saugns.c Add -v verbose option, rename version to -V. 3 weeks ago
saugns.h Add -v verbose option, rename version to -V. 3 weeks ago
test-scan.c Add -v verbose option, rename version to -V. 3 weeks ago
wave.c Add '--mono' and '--stdout' cli options. 3 weeks ago
wave.h Rename project to 'saugns' from 'sgensys'. 3 weeks ago

README.md

saugns is the Scriptable AUdio GeNeration System, the implementation of the SAU (Scriptable AUdio) language. The project website has more on them.

SAU is a simple language for mathematical audio synthesis, without support for using pre-recorded samples. See doc/README.SAU for the details in the present version, or a more how-to web page covering the main features. Example scripts under examples/ also use most features.

While the language is still primitive relative to the goal (a useful language for writing electronic music), it makes it simple to experiment with sounds. A collection of basic wave types are supported, as well as AM/RM, FM, and PM (the "FM" of most commercial synthesizers). An arbitrary number of oscillators can be used.

The program reads SAU (Scriptable AUdio) files or strings, and can output to system audio, a 16-bit PCM WAV file, and/or stdout (raw or AU, for interfacing with other programs). Basic usage information is provided with the -h option. More can be found in the man page and on the usage web page.

Tested mainly on x86 and x86-64. Comes with support for running on DragonFly, FreeBSD, Linux, NetBSD, and OpenBSD. The following audio systems are expected:

OS Supported APIs
DragonFly OSS
FreeBSD OSS
Linux ALSA, OSS
NetBSD OSS
OpenBSD sndio

Building and installing

Building requires a C99 compiler toolchain, running make, and having some GNU or BSD tools. There is no "configure" step.

On Linux distributions, the ALSA library (libasound2) or a '-dev' package or similar for it may possibly need to be installed for building to work. In the cases of the 4 major BSDs, the base systems have it all.

A simple test after building is the following, which should play a sine wave at 440 Hz for 1 second: ./saugns -e "Osin".

Running make install will by default copy saugns to /usr/local/bin/, and the contents of doc/ and examples/ to directories under /usr/local/share/.

Files under share/ Description
doc/saugns/README.md This file.
doc/saugns/README.SAU SAU language reference.
examples/saugns/ Example scripts.

A make uninstall removes the added saugns binary and share/ subdirectories. It's recommended before installing a new version, for a consistent file set.

After installation, man saugns should give basic usage information and point to the share/ files. Without installing, try man ./man/saugns.1.

Tweaking the build

As of v0.3.9, an anti-aliasing oscillator with 6dB aliasing reduction per octave is used. v0.3.10b fixed the problem of it audibly producing jagged (somewhat bitcrush-looking) waveforms when higher PM amplitudes are used. But there could be other reasons to use a simpler alternative.

The USE_PILUT option in renderer/osc.h defaults to 1 (on) but can be set to 0 before (re-)running make to switch to using the pre-v0.3.9 naive oscillator instead. While the naive oscillator is bad for square and sawtooth waves especially, it's fine for use with sine wave-based PM.

This may all be replaced in later versions.

Licensing

saugns is Copyright (c) 2011-2014, 2017-2022 Joel K. Pettersson. As a whole it is distributed under the terms of the GNU Lesser General Public License (LGPL), version 3 or later. See the file COPYING for details, or https://www.gnu.org/licenses/lgpl-3.0.en.html.

Some files are licensed under more permissive terms, such as the ISC license (2-clause-BSD-equivalent), or the 0BSD license (public-domain-equivalent shorter version); see the heading comment text of source files.

The example and test scripts included as input for the program are (unlike other potential works) meant for study and copying from. Feel free to copy from them for your own scripts without any attribution or licensing text. If that's not enough in the future, WTFPL and/or a Creative Commons license could be used.

Documentation

Included documentation files (man page, this and others placed under doc/) are written by Joel K. Pettersson and licensed under Creative Commons Attribution-ShareAlike 4.0. These files are maintained and provided in parallel with the website.

Contributing

Bug reports are very welcome, with or without fixes. Many bugs could have been fixed much sooner if only they had been found earlier.

General feedback, ideas, and proposed changes are also welcome. I'm open to extending and reworking the SAU language, though features will always be limited. Most valuable are those things that may provide the most with the least. I'm looking to increase flexibility and elegance, with a smaller number of added things.