.\" -*- nroff -*-
.\"
.\" aylet 0.4, a .AY music file player.
.\" Copyright (C) 2001-2004 Russell Marks and Ian Collier.
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
.\"
.\"
.\" aylet.1 - man page
.\"
.TH aylet 1 "1st October, 2004" "Version 0.4" "Music Software"
.\"
.\"------------------------------------------------------------------
.\"
.SH NAME
aylet, xaylet \- play Spectrum `.ay' music files
.\"
.\"------------------------------------------------------------------
.\"
.SH SYNOPSIS
.PD 0
.BR aylet / xaylet
.RB [ -BehlmnNsS ]
.RB [ -A
.IR stopafter ]
.RB [ -F
.IR fadetime ]
.RB [ -t
.IR tracknum ]
.RI [ file1
.RI [ file2
.cc @
... ]]
@cc .
.P
.PD 1
.\"
.\"------------------------------------------------------------------
.\"
.SH DESCRIPTION
aylet plays music files in the `.ay' format. These files are
essentially wrappers around bits of Z80 code which play music on the
Sinclair ZX Spectrum 128's sound hardware - the beeper, or the
AY-3-8912 sound chip, or both. Files using the Amstrad CPC ports are
also supported.

`aylet' has a curses-based interface, and `xaylet' has an X-based one.
.\"
.\"------------------------------------------------------------------
.\"
.SH OPTIONS
.TP
.B -A
set stop-after time in seconds (this is the time at which tracks start
fading out), or 0 to disable fading. The default is 180 seconds (3
minutes).
.TP
.B -B
use `ABC' stereo positions, rather than the default `ACB'. ACB
effectively pushes channels A and B to the left and right (using a
stereo delay), with C remaining central; ABC puts A and C to the
left/right instead, leaving B central.
.TP
.B -e
force 8-bit playback, even if 16-bit is available.
.TP
.B -F
set fade-out time in seconds (the time tracks take to fade out). The
default is 10 seconds.
.TP
.B -h
give terse usage help.
.TP
.B -l
list the contents of files (track names etc.) rather than playing
them.
.TP
.B -m
use mono rather than the default stereo playback.
.TP
.B -n
rather than the usual interface, use a simple batch-playing tty style,
a bit like mpg123. (Only works in the curses version.)
.TP
.B -N
use `narrow' stereo separation (so the channels sound closer together)
rather than the default `wide' separation.
.TP
.B -s
output sample data to stdout rather than playing it; implies `-n'. The
sample is 44.1kHz 16-bit stereo (or mono if using `-m'). Don't be
surprised if the sample takes a little while to generate, as it still
has to emulate the Z80.
.TP
.B -S
apply a pseudo-stereo effect to the beeper output. Works well in some
cases, but can make things sound a bit shaky (or rather, more so than
usual :-)).
.TP
.B -t
play only the specified track, then exit. (Strictly speaking, it
starts playing the given track, and exits when any track fades out.)
Mainly useful when playing a single file non-interactively.
.TP
.IR file1 " etc."
the file(s) to play. Currently these can only be specified on the
command-line.
.\"
.\"------------------------------------------------------------------
.\"
.SH "BEHIND THE SCENES"
The way aylet works may seem a little strange if you're not familiar
with how the `.ay' format goes about things, so here's some background
on how it all works.
.PP
As mentioned above, the files basically contain chunks of machine
code to run on an emulated Z80 with certain sound hardware. Since
you're just running a program, you can't really fast-forward or rewind
as such, but you can move between tracks specified in the file. (Some
files only have one, but others have several.)
.PP
The whole just-running-a-program thing leads to two other problems,
too. You can't tell where a track ends, other than to see when the
sound stops; what aylet does is to exit a track after 4 seconds of
total silence. And a track may never end at all; aylet fades it out
after 3 minutes by default. (Yes, 3 minutes be may too soon to allow
some tracks to `finish', but you have to strike the balance somewhere,
and it's only a default. Use `-A' or press `s' to change it.)
.\"
.\"------------------------------------------------------------------
.\"
.SH KEYS
Both the curses-based and X-based interfaces use these keys (some of
which are based on those used by XMMS):
.TP
.IR q " or " Esc
exit the program.
.TP
.I z
previous track.
.TP
.I x
play.
.TP
.I c
pause.
.TP
.I v
stop.
.TP
.I b
next track.
.TP
.I r
restart track.
.TP
.IR Backspace " or " Delete
previous file.
.TP
.I Space
next file.
.TP
.I s
increase stop-after time.
.TP
.I S
decrease stop-after time. Setting it to zero disables fading
completely.
.TP
.I f
increase fade-out time.
.TP
.I F
decrease fade-out time.
.TP
.I h
enable/disable high-speed mode, playing four times as fast when
enabled (in a way), as a sort of substitute for a real fast-forward
control.
.PP
In xaylet, you can also use the matching buttons for most of the
above.
.PP
When using `aylet -n', the interactivity is scaled down dramatically,
leaving just the one control:
.TP
.I Ctrl-C
if the current track has been playing for less than half a second,
exit the program; otherwise, skip to the next track.
.PP
Note that the key used to do this is really whatever you have set up
to generate a SIGINT signal, but it's generally Ctrl-C.
.\"
.\"------------------------------------------------------------------
.\"
.SH EXAMPLES
To play all .ay files in the current directory:
.PP
aylet *.ay
.br
or
.br
xaylet *.ay
.PP
To convert ysfollin.ay to a mono sample in .wav format (requires
`sox'):
.PP
aylet -sm ysfollin.ay |sox -r 44100 -t sw - tune.wav
.\"
.\"------------------------------------------------------------------
.\"
.SH BUGS
The AY is probably too loud relative to the beeper. This may be fixed
in the next version, though it's more likely to be an option to choose
between the current more reasonable balance and the real thing. :-)
.PP
Several options which it could reasonably allow to be changed at
runtime (e.g. AY stereo, beeper stereo, ACB vs. ABC) can't be at the
moment.
.PP
The X version is currently a bit too much like the curses one, at the
expense of GUIness in some respects.
.\"
.\"------------------------------------------------------------------
.\"
.SH SEE ALSO
.IR fuse "(1)"
.\"
.\"------------------------------------------------------------------
.\"
.SH AUTHOR
Russell Marks (rus@svgalib.org).
.PP
The Z80 emulation was written by Ian Collier, for xz80.
.PP
Chris Cox wrote the OpenBSD sound code.
.PP
Matan Ziv-Av was partly responsible for the OSS sound code.