taylet - a player for Spectrum `.ay' music files (derived from aylet 0.5).
Copyright (C) 2001-2005 Russell Marks.
Z80 emulation copyright (C) 1994 Ian Collier.
Modifications copyright (C) 2025-2026 Jérôme SONRIER.

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, see <https://www.gnu.org/licenses/>.


About taylet
------------

taylet is a fork of aylet 0.5 by Russell Marks, the last release of the
original project (2005). It is distributed under the same terms as
aylet: the GNU General Public License, version 2 or (at your option)
any later version.

Source code: https://salsa.debian.org/emor3j/taylet

Changes compared to aylet 0.5 are recorded in the git history. The
original, unmodified aylet 0.5 is the commit tagged `aylet-0.5'.

So far:

  - the curses (`aylet') and GTK+ (`xaylet') interfaces have been
    removed; taylet no longer depends on ncurses or GTK+. It is now a
    plain command-line player;
  - the emulation (Z80, AY and beeper sound, .ay files, player) is a
    separate core in src/core, which knows nothing about the
    interfaces: src/cli is the command-line player, and the audio
    output drivers are in src/drivers and src/sdl;
  - the build system is now CMake;
  - the default build has no dependency and no audio driver: it sends
    raw PCM to standard output (`-s');
  - taylet-sdl, an optional build which plays the sound through SDL2;
  - taylet-kde, an optional Qt 6 / KDE Frameworks 6 graphical player,
    under development: it opens files, keeps a play list of their
    tracks and plays them in sequence (src/qt: audio output, play list
    and control of the core, src/kde: the interface). Its settings
    (stereo, fade-out...) are in a settings dialog, kept with KConfigXT,
    and it keeps its play list from one run to the next. Only one
    instance runs at a time (KDBusService), and it can be controlled
    through MPRIS2 (media keys, desktop media controls, playerctl).
    It has an icon, a menu entry and a MIME type for .ay files, and it
    is translated into French, German, Spanish, Italian, Russian,
    Simplified Chinese and Japanese (po/). The menu entry and the
    AppStream file are translated too.


Description
-----------

taylet 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 - either the beeper, or
(eponymously) the AY-3-8912 sound chip. Files using the Amstrad CPC
ports are also supported.

taylet has no interactive interface: it plays the files given on the
command line, one track after the other, and exits after the last one
(or when you press Ctrl-C).

Three programs can be built:

  taylet      no dependency. By default it has no audio driver and
              writes raw samples to standard output (`-s'), to be sent
              to a player such as aplay; it can also be built with an
              OSS or OpenBSD audio driver.
  taylet-sdl  plays the sound by itself through SDL2, so it works with
              PipeWire, PulseAudio or ALSA without any other program.
  taylet-kde  a graphical player with a play list, using Qt 6 and the
              KDE Frameworks 6 (still under development).

taylet and taylet-sdl take the same options (see the man pages), except
that `-s' only exists in taylet. taylet-kde has no such options: it is
used through its window (the settings are in a settings dialog), and
takes the files to play on the command line.

One source of `.ay' files playable with taylet is "Project AY" on the
World of Spectrum website:

  http://www.worldofspectrum.org/


Installation
------------

You need CMake (3.18 or later) and a C compiler. taylet-sdl also needs
the SDL2 development files (libsdl2-dev on Debian).

  cmake -S . -B build
  cmake --build build
  ctest --test-dir build         (optional: run the tests)
  cmake --install build          (as root, or with DESTDIR=...)

The usual variables (CMAKE_BUILD_TYPE, CMAKE_INSTALL_PREFIX, CFLAGS,
LDFLAGS, DESTDIR...) are honoured. What is built is chosen with
options; nothing is enabled or disabled automatically depending on
what is installed, and asking for something which cannot be built is
an error:

  -DTAYLET_BUILD_CLI=ON    build taylet (default: ON).
  -DTAYLET_BUILD_SDL=ON    build taylet-sdl, which needs SDL2
                           (default: OFF).
  -DTAYLET_BUILD_KDE=ON    build taylet-kde, which needs Qt 6 (Widgets,
                           Multimedia) and KDE Frameworks 6 (Config,
                           ConfigWidgets, CoreAddons, DBusAddons, I18n,
                           WidgetsAddons, WindowSystem, XmlGui) with
                           extra-cmake-modules (default: OFF).
  -DTAYLET_BUILD_TESTS=OFF do not build the tests (default: ON).
  -DTAYLET_WARNINGS=OFF    do not pass -Wall to the compiler.

Audio driver of taylet (it does not apply to taylet-sdl, which always
uses SDL2):

  -DTAYLET_DRIVER=none     no audio device; raw PCM on stdout only (`-s').
                           This is the default and has no dependency.
  -DTAYLET_DRIVER=oss      OSS output (/dev/dsp).
  -DTAYLET_DRIVER=openbsd  OpenBSD native audio output.

The OSS and OpenBSD drivers are inherited from aylet and have not been
tested since the changes made in taylet.

For example, to build both programs:

  cmake -S . -B build -DTAYLET_BUILD_SDL=ON


Usage
-----

With taylet-sdl:

  taylet-sdl file.ay

With taylet and its default driver:

  taylet -s file.ay | aplay -f S16_LE -c 2 -r 44100

(`-s' writes 44.1kHz 16-bit stereo samples using the machine's native
byte ordering; see the man page for -m and -e.)

SDL chooses the audio system itself; the SDL_AUDIODRIVER environment
variable overrides its choice (for example SDL_AUDIODRIVER=alsa).

With taylet-kde:

  taylet-kde [file.ay ...]

The settings are in the Settings menu (Configure Taylet...) and are kept
in ~/.config/tayletrc. The play list is kept in
~/.local/state/tayletstaterc and comes back when taylet-kde is started
without any file (this can be turned off in the settings).

Only one taylet-kde runs at a time in a session. Starting it again
with files replaces the play list of the running one with them, as on a
first start, and brings its window to the front.

taylet-kde implements MPRIS2 (org.mpris.MediaPlayer2.taylet), so the
media keys and the media controls of the desktop work; for example:

  playerctl -p taylet play-pause
  playerctl -p taylet metadata


Translations
------------

taylet-kde is translated with ki18n (gettext): the messages are in
po/taylet.pot, and the translation into a language is po/<language>/taylet.po.
The translations made so far were written by an AI assistant and have not
been reviewed by native speakers: corrections are welcome.

The texts of the menu entry (src/kde/org.eu.fr.emor3j.taylet.desktop) and
of the AppStream file (src/kde/org.eu.fr.emor3j.taylet.metainfo.xml) are
translated inside these files, not in po/: when one changes, change all of
its translations.

sh po/extract-messages.sh    after a message was added or changed: it
                             makes po/taylet.pot again and merges it into
                             the .po files (needs gettext).

To add a language, make po/<language>/taylet.po from the template, for
example with `msginit -i po/taylet.pot -l pt -o po/pt/taylet.po', then
translate it. It is installed with the program, nothing else needs to be
changed. To try a language without installing the program in the system:

  cmake --install build --prefix /tmp/taylet
  XDG_DATA_DIRS=/tmp/taylet/share LANGUAGE=fr /tmp/taylet/bin/taylet-kde


Other files
-----------

The COPYING file contains a copy of the GPL described above.

NEWS and ChangeLog describe differences between versions.


Contacting me
-------------

For taylet, contact Jérôme SONRIER <jsid@emor3j.fr.eu.org>.

The original aylet was written by Russell Marks (rus@svgalib.org).
