src/usr.bin/aucat/aucat.1 - diff

Return to aucat.1 CVS log

Up to [local] / src / usr.bin / aucat

Diff for /src/usr.bin/aucat/aucat.1 between version 1.93 and 1.94

version 1.93, 2011/11/15 09:07:45

version 1.94, 2011/12/09 14:36:42

Line 18

.Dt AUCAT 1

.Os

.Sh NAME

.Nm aucat

.Nm aucat ,

.Nm sndiod

.Nd audio/MIDI server and stream manipulation tool

.Sh SYNOPSIS

.Nm aucat

.Bk -words

.Op Fl dlMn

.Op Fl dn

.Op Fl a Ar flag

.Op Fl b Ar nframes

.Op Fl C Ar min : Ns Ar max

.Op Fl c Ar min : Ns Ar max

Line 33

.Op Fl h Ar fmt

.Op Fl i Ar file

.Op Fl j Ar flag

.Op Fl L Ar addr

.Op Fl m Ar mode

.Op Fl o Ar file

.Op Fl q Ar port

.Op Fl r Ar rate

.Op Fl t Ar mode

.Op Fl v Ar volume

.Op Fl w Ar flag

.Op Fl x Ar policy

.Op Fl z Ar nframes

.Ek

.Nm sndiod

.Bk -words

.Op Fl dM

.Op Fl a Ar flag

.Op Fl b Ar nframes

.Op Fl C Ar min : Ns Ar max

.Op Fl c Ar min : Ns Ar max

.Op Fl e Ar enc

.Op Fl f Ar device

.Op Fl j Ar flag

.Op Fl L Ar addr

.Op Fl m Ar mode

.Op Fl q Ar port

.Op Fl r Ar rate

.Op Fl s Ar name

.Op Fl t Ar mode

.Op Fl U Ar unit

Line 50

Line 69

.Nm

is an audio utility which can simultaneously play and record

any number of audio

.Em streams

.Em streams ,

on any number of audio devices,

possibly controlled through MIDI.

It can also act as an audio server, in which case streams

correspond to client connections rather than plain files.

.Pp

Audio devices are independent.

A list of streams is attached to each audio device,

as well as an optional list of MIDI ports to control the device.

A typical invocation of

.Nm

consists in providing streams to play and record,

and possibly the audio device to use, if the default is not desired.

and possibly the audio device to use.

.Pp

This also applies to server mode, except that streams are created

The

.Nm sndiod

daemon acts as an audio server.

Its functionality is identical to

.Nm aucat ,

except that streams are created

dynamically when clients connect to the server.

Thus, instead of actual streams (paths to plain files),

templates for client streams (sub-device names) must be provided.

Multiple independent audio devices are supported,

each has its own list of streams and MIDI control ports.

.Pp

The options are as follows:

.Bl -tag -width Ds

.It Fl a Ar flag

Control whether

.Nm

.Nm sndiod

opens the audio device only when needed or keeps it open all the time.

This applies to MIDI ports controlling the device as well.

If the flag is

Line 101

Line 120

The default is 0:1, i.e. stereo.

.It Fl d

Increase log verbosity.

.Nm

.Nm sndiod

logs on

.Em stderr

until it daemonizes.

Line 146

Line 165

The default is

.Ar on .

.It Fl L Ar addr

Specify a local network address to listen on in server mode.

Specify a local network address

.Nm

.Nm sndiod

should listen;

.Nm sndiod

will listen on TCP port 11025+n, where n is the unit number

specified with

.Fl U .

Without this option,

.Nm

.Nm sndiod

listens on the

.Ux Ns -domain

socket only, and is not reachable from any network.

If the option argument is

.Sq -

then

.Nm

.Nm sndiod

will accept connections from any address.

.It Fl l

Detach and become a daemon.

.It Fl M

Create a MIDI thru box

.Pq i.e. MIDI-only pseudo device .

Line 177

Line 196

.Fl m Ar midi

.Pc

can be attached to it.

If sub-devices are exposed

Exposed sub-devices by

.Pq Fl s

.Nm sndiod

they behave like software MIDI ports,

behave like software MIDI ports,

allowing any MIDI-capable application to send MIDI messages to

MIDI hardware or to another application in a uniform way.

.It Fl m Ar mode

Line 208

Line 227

.Pq Fl i

and one output

.Pq Fl o .

It doesn't support MIDI control

.Pq Fl q

and can't expose sub-devices

.Pq Fl s .

.It Fl o Ar file

Add this file to the list of recording streams.

If the option argument is

Line 233

Line 248

.It Fl s Ar name

Add

.Ar name

to the list of sub-devices to expose in server mode.

to the list of sub-devices to expose.

This allows clients to use

.Nm

.Nm sndiod

instead of the physical audio device for audio input and output

in order to share the physical device with other clients.

Defining multiple sub-devices allows splitting a physical audio device

Line 262

Line 277

.It Fl U Ar unit

Unit number to use when running in server mode.

Each

.Nm

.Nm sndiod

server instance has an unique unit number,

used in

.Xr sndio 7

device names.

The default is 0.

The unit number must be set before any server-specific

The unit number must be set before any

options are used

.Fl L

.Pq Fl Ls .

is used.

.It Fl v Ar volume

Software volume attenuation of the playback stream.

The value must be between 1 and 127,

Line 284

Line 299

.It Fl w Ar flag

Control

.Nm

and

.Nm sndiod

behaviour when the maximum volume of the hardware is reached

and a new stream is connected.

This happens only when stream volumes

Line 357

Line 374

must follow the definition of the device

.Pq Fl fMn

to which they are attached.

Global parameters

.Pq Fl dl

are position-independent.

.Pp

If no audio devices

.Pq Fl fMn

are specified,

settings are applied as if

the default device is specified.

If no streams

If no

.Pq Fl ios

.Nm sndiod

sub-devices

.Pq Fl s

are specified for a device, a default server sub-device is

created attached to it, meaning that

created attached to it.

.Nm

behaves as an audio server.

If a device

.Pq Fl fMn

is defined twice, both definitions are merged:

Line 382

Line 396

of both definitions are created.

The default

.Xr sndio 7

device is

device used by

.Pa snd/0

.Nm sndiod

.Pq also known as Pa snd/0.default .

.Pa rsnd/0 ,

and the default sub-device exposed by

.Nm sndiod

.Pa snd/0 .

.Pp

.Nm

.Nm sndiod

.Nm aucat

is sent

.Dv SIGHUP ,

.Dv SIGINT

Line 475

Line 496

unsigned 18-bit, packed in 3 bytes, big endian

.El

.Sh SERVER MODE

If at least one sub-device

.Nm sndiod

.Pq Fl s

can be used

is exposed by

.Nm ,

including the case when no stream options are given,

then

.Nm

can be used as a server

to overcome hardware limitations and allow applications

to run on fixed sample rate devices or on devices

supporting only unusual encodings.

Line 502

Line 517

.Pq Fl q

and allows audio device properties to be controlled

through MIDI.

If running in server mode

Additionally,

.Nm

.Nm sndiod

creates a MIDI port with the same name as the default audio

creates a MIDI port with the same name as the exposed audio

device to which MIDI programs can connect.

sub-device to which MIDI programs can connect.

.Pp

A MIDI channel is assigned to each stream, and the volume

is changed using the standard volume controller (number 7).

Line 524

Line 539

and recording must start.

If the requested position is beyond the end of file,

the stream is temporarly disabled until a valid position is requested.

This message is ignored by client streams (server mode).

This message is ignored by audio

The given time position is sent to MIDI ports as an MTC

.Nm sndiod

clients, but the given time position is sent to MIDI ports as an MTC

.Dq "full frame"

message forcing all MTC-slaves to relocate to the given

position (see below).

.It start

Put all streams in starting mode.

In this mode,

.Nm

.Nm sndiod

.Nm aucat

waits for all streams to become ready

to start, and then starts them synchronously.

Once started, new streams can be created (server mode)

Once started, new streams can be created

.Pq Nm sndiod

but they will be blocked

until the next stop-to-start transition.

.It stop

Put all streams in stopped mode (the default).

In this mode, any stream attempting to start playback or recording

is paused.

Files are stopped and rewound back to the starting position,

Files

while client streams (server mode) that are already

.Pq Nm aucat

are stopped and rewound back to the starting position,

while client streams

.Pq Nm sndiod

that are already

started are not affected until they stop and try to start again.

.El

.Pp

Streams created with the

.Fl t

option export the server clock using MTC, allowing non-audio

option export the

.Nm sndiod

device clock using MTC, allowing non-audio

software or hardware to be synchronized to the audio stream.

Maximum accuracy is achieved when the number of blocks per

second is equal to one of the standard MTC clock rates (96, 100 and 120Hz).

Line 576

Line 601

and a MIDI-controlled

.Va snd/0.mmc :

.Bd -literal -offset indent

$ aucat -l -r 48000 -z 400 -s default -t slave -s mmc

$ sndiod -r 48000 -z 400 -s default -t slave -s mmc

.Ed

.Pp

Streams connected to

Line 634

Line 659

-o right.wav

.Ed

.Pp

Start

Start server using default parameters, creating an

.Nm

in server mode using default parameters, creating an

additional sub-device for output to channels 2:3 only (rear speakers

on most cards), exposing the

.Pa snd/0

Line 644

Line 667

.Pa snd/0.rear

devices:

.Bd -literal -offset indent

$ aucat -l -s default -c 2:3 -s rear

$ sndiod -s default -c 2:3 -s rear

.Ed

.Pp

Start

Start server creating the default sub-device with low volume and

.Nm

in server mode, creating the default sub-device with low volume and

an additional sub-device for high volume output, exposing the

.Pa snd/0

and

.Pa snd/0.max

devices:

.Bd -literal -offset indent

$ aucat -l -v 65 -s default -v 127 -s max

$ sndiod -v 65 -s default -v 127 -s max

.Ed

.Pp

Start

Start server configuring the audio device to use

.Nm

in server mode, configuring the audio device to use

a 48kHz sample frequency, 240-frame block size,

and 2-block buffers.

The corresponding latency is 10ms, which is

the time it takes the sound to propagate 3.5 meters.

.Bd -literal -offset indent

$ aucat -l -r 48000 -b 480 -z 240

$ sndiod -r 48000 -b 480 -z 240

.Ed

.Sh SEE ALSO

.Xr audioctl 1 ,

Line 682

Line 701

It will not work reliably on files that may block

(ordinary files block, pipes don't).

To avoid audio underruns/overruns or MIDI jitter caused by file I/O,

it's recommended to use two

it's recommended to use two processes: a

.Nm sndiod

server handling audio and MIDI I/O and a

.Nm

processes: a server handling audio and MIDI I/O and a client handling

client handling disk I/O.

disk I/O.

.Pp

Resampling is low quality; down-sampling especially should be avoided

when recording.

Line 696

Line 716

.Pp

.Fl a Ar off

is used in server mode,

is used,

.Nm

.Nm sndiod

creates sub-devices to expose first

and then opens the audio hardware on demand.

Technically, this allows

.Nm

.Nm sndiod

to attempt to use one of the sub-devices it exposes as an audio device,

creating a deadlock.

To avoid this,