README.md

ctracker

A terminal (ncurses) music tracker module player supporting Impulse Tracker (.it), Scream Tracker 3 (.s3m), ProTracker/Amiga MOD (.mod) and FastTracker II Extended (.xm) files.

Requirements

• CMake >= 3.16
• A C11 compiler (gcc or clang)
• pkg-config
• ncursesw and an ALSA/PulseAudio development environment (see sdd-flow/environment/setup-env.sh for the full toolchain this project is provisioned with)
• libopenmpt (the playback core) >= 0.3.0, development package (e.g. libopenmpt-dev on Debian/Ubuntu), located via pkg-config
• Valgrind (for ./test.sh --valgrind)

Build

./build.sh

This runs cmake -S . -B build && cmake --build build, producing build/ctracker.

Test

./test.sh

Runs the CTest suite (ctest --test-dir build) against the build produced by ./build.sh.

Memory-safety verification (ASan/UBSan + Valgrind)

./test.sh --asan       # configure/build build-asan/ with -DCTK_SANITIZE=address
                        # (-fsanitize=address,undefined) and run the suite under it
./test.sh --valgrind   # run the normal build's suite under Valgrind via
                        # `ctest -T memcheck` (full leak-check, error-exitcode)

Both paths are required to stay clean (NREQ-003); ./test.sh --asan can also be driven directly with cmake -S . -B build-asan -DCTK_SANITIZE=address.

Run

./build/ctracker <file>

To check the installed version:

./build/ctracker --version

Project layout

src/cli/            Application entry point / CLI argument parsing
src/core/           Playback core: module loading, decoding, transport and
                    introspection, backed by libopenmpt
src/audio/          Audio device output (miniaudio)
src/tui/            ncurses terminal UI
third_party/miniaudio/  Vendored miniaudio.h (pinned, see NOTES.md) and its
                        single MINIAUDIO_IMPLEMENTATION translation unit
tests/              CTest unit and integration/smoke tests