ref: 25263b582955f7ba4086960c4440a22c7aa94921
dir: /soxlua.7/
'\" t
'\" The line above instructs most `man' programs to invoke tbl
'\"
'\" Separate paragraphs; not the same as PP which resets indent level.
.de SP
.if t .sp .5
.if n .sp
..
'\"
'\" Replacement em-dash for nroff (default is too short).
.ie n .ds m " -
.el .ds m \(em
'\"
'\" Placeholder macro for if longer nroff arrow is needed.
.ds RA \(->
'\"
'\" Decimal point set slightly raised
.ds d \v'-.15m'.\v'+.15m'
'\"
.TH SoX 7 "January 31, 2007" "soxlua" "Sound eXchange"
.SH NAME
soxlua\*mLua scripting of SoX
.SH DESCRIPTION
This man page explains how to write SoX effects and file formats in
Lua. For documentation of Lua, see http://www.lua.org/; SoX currently
uses Lua 5.1, whose manual can be found at
http://www.lua.org/manual/5.1/manual.html. For details of the workings
of SoX effects and formats, see
.BR libst (3) .
The Lua programming interface is a simplified version of that for C.
.SH GENERAL
SoX embeds a Lua interpreter with all the standard libraries
available. This might change in future to make SoX more secure; in
particular, format and effects scripts intended to be future-proof
should not use the os library, and only use the io library on file
handles supplied by SoX.
.SP
SoX adds support to Lua for arrays of st_sample_t. These arrays can be
used like normal Lua tables, but are of fixed size. As normal in Lua,
they are one-based, that is, the valid incides for an array `a' are
from 1 to #a inclusive.
.SH EFFECTS
Effects are extremely simple: the Lua script is passed all its input
as a single st_sample_t array, and should return its output as a
normal Lua table. The output values should be of the same type (i.e.
32-bit signed integers), though in fact Lua stores all numbers as
floating point, typically as type double. This is not a problem, as
the mantissa of double normally holds more than 32 bits.
.SH FORMATS
A format is a table containing three functions, thus:
.SP
{
read = function (fh, ibuf) ... return isamp ... end,
write = function (fh, obuf) ... return osamp ... end,
seek = function (fh, offset) ... return ret ... end,
}
.SP
where \fIfh\fR is a file handle, \fIibuf\fR and \fIobuf\fR are arrays
of st_sample_t to read into or out of, respectively, the length of the
arrays indicating how many items should be read or written at most,
and \fIoffset\fR is the number of samples to seek by relative to the
current position. The return values indicate respectively how many
samples were read or written, and for the `seek' method, a boolean
indicating whether the seek was successful.
.SH SEE ALSO
.BR sox (1),
.BR libst (3)
.SH AUTHORS
This man page was written by Reuben Thomas (rrt@sc3d.org).