au-utils/file2au.1

.Dd Jul 17, 2017
.Dt FILE2AU 1
.Os
.Sh NAME
.Nm file2au
.Nd decode an Au formatted stream from an audio file
.Sh SYNOPSIS
.Nm
.Op Fl C Ar command-fd
.Op Fl I Ar info-fd
.Op Fl b Ar buffer-size
.Op Fl c Ar command-file
.Op Fl i Ar info-file
.Sh DESCRIPTION
.Nm
writes an Au formatted audio stream, converting from the
.Sy file
format.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl C Ar command-fd
Use the specified file-descriptor as the command input.
.It Fl I Ar info-fd
Use the specified file-descriptor as the information output as opposed
to the standard error.
.It Fl b Ar buffer-size
Override the default buffer size.
.It Fl c Ar command-file
Use the specified file as the command input.
.It Fl i Ar info-file
Use the specified file as the information output as opposed to the
standard error.
.It Fl v
Automatically print to the information output.  See the
.Ic \?
command below.
.El
.Pp
The command input will recognize the following simple commands, and
ignore any other input:
.Bl -tag -width Ds
.It Ic time | =time | =+time
Seek to
.Ic time ,
relative to the start.
.It Ic =-time
Seek to
.Ic time ,
relative to the end.
.It Ic +time | -time
Seek
.Ic time
from the current position.
.It Ic \?
Print the current time and total time separated by a solidus
.Pq Li /
.It Ic q
Stop decoding, close the file, and exit.
.It Ic z Ar frequency
Set the frequency of information printing with
.Fl v
in hertz. The default is 1000.
.El
.Sh EXAMPLES
Play an audio file:
.Pp
.Dl file2au < file | au2dev
.Pp
Convert from high to low quality lossy compression:
.Pp
.Dl file2au < high | au2file -q0.1 > low
.Pp
Use the command input to seek ten and a half seconds into a two minute
file:
.Bd -literal -offset indent
$ file2au -c command.fifo < file | ... &
$ echo '10.5?' > command.fifo
10.5/120
.Ed
.Pp
Poll the current position every second:
.Bd -literal -offset indent
$ while sleep 1; do
> 	echo '?' > command.fifo
> done
11.5/120
12.5/120
13.5/120
...
.Ed
.Pp
Stop decoding, closing the file, and quit:
.Bd -literal -offset indent
$ file2au -c command.fifo < file | au2dev &
$ echo q > command.fifo
$
[1]   Done                    file2au -c command.fifo < file | au2dev
$
.Ed
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
.Xr au 7
.Xr auopen 1
.Xr auconv 1
.Xr audev 1
.Xr file2au 1
.Xr flac 1
.Xr oggdec 1
.Xr oggenc 1
.Sh BUGS
Variable sample rates/widths are unsupported.