Files

T

Jason 1f17cf04b4 Refactor: modularize code into separate files with enhanced documentation

- Split paula.cpp and modplayer.cpp into separate compilation units
- Created config.h for centralized configuration constants
- Created types.h for type definitions and utility functions
- Added comprehensive comments throughout all files
- Improved code organization with clear section dividers
- Maintained all original functionality and logic

2026-04-24 19:36:30 +10:00

3.6 KiB

Raw Blame History

TinyMOD - Amiga MOD File Player

TinyMOD is a high-fidelity Amiga MOD (Protracker format) file player that authentically recreates the sound characteristics of original Amiga hardware through software emulation of the Paula audio chip.

Features

Authentic Paula Chip Emulation: Faithfully replicates the Amiga Paula chip sound by operating at the original master clock rate (3.5 MHz) and downsampling to standard output rates
Protracker Support: Full support for MOD file format with all standard effects
High-Quality Resampling: Uses windowed-sinc FIR filtering for excellent audio quality
4-Channel Audio: Stereo output with proper channel mixing and panning
Effect Processing: Complete MOD effect support including:
- Vibrato and tremolo
- Pitch slides and portamento
- Volume slides
- Arpeggio
- Pattern looping and breaking
- And more...

Building

Requirements

GCC/G++ compiler
PortAudio library (libportaudio.a)
ALSA development libraries (for Linux)
Make

Compilation

make

The Makefile will:

Compile the modular source files
Link with PortAudio and system libraries
Create the tinymod executable

Cleanup

make clean

Usage

Playing a MOD File

./tinymod music.mod

Getting Help

./tinymod --help

About

./tinymod --about

Architecture

The codebase is organized into modular components:

Core Modules

src/types.h: Type definitions, memory utilities, and mathematical functions
src/config.h: Centralized configuration constants
src/paula.h/src/paula.cpp: Amiga Paula chip emulator
src/modplayer.h/src/modplayer.cpp: MOD file parser and playback engine
src/main.cpp: Command-line interface and audio system integration

Design Principles

Modular Design: Each component has a single responsibility
Well-Documented: Extensive comments explaining algorithms and MOD format details
Portable: Platform-independent code with PortAudio for audio I/O
Authentic: Preserves original Paula chip behavior and MOD effect processing

Technical Details

Paula Chip Emulation

The Paula emulator processes audio at the original Amiga clock rate (3,740,000 Hz) and applies:

PWM (Pulse Width Modulation) for sample playback
Ring buffer for sample storage
Windowed-sinc FIR filter for high-quality resampling

MOD Format Support

Supports the following MOD file variants:

Standard MOD (4 channels, 16-32 samples)
M.K. format (32 samples)
FLT4 (Startrekker, 32 samples)
M!K! (extended patterns, 32 samples)

Effect Processing

All major Protracker effects are implemented:

0x: Arpeggio
1x: Slide up
2x: Slide down
3x: Tone portamento
4x: Vibrato
5x: Tone portamento + volume slide
6x: Vibrato + volume slide
7x: Tremolo
9x: Sample offset
Ax: Volume slide
Bx: Position jump
Cx: Set volume
Dx: Pattern break
Ex: Extended effects
Fx: Set speed/BPM

Authors

Tammo "kb" Hinrichs - Original Paula emulator implementation (2007)
Jason Bou-samra - Code refactoring, modularization, and PortAudio integration (2024)

License

This software is released into the public domain. Use, distribute, and modify freely without restriction.

Notes

High-quality Paula emulation requires significant CPU resources due to the 3.5 MHz -> 48 KHz resampling ratio
Playback duration is configurable via NUM_SECONDS constant in config.h
Audio output can be customized through PortAudio configuration

References

Protracker MOD Format Documentation
Amiga Hardware Specifications
Paula Chip Audio Hardware Documentation

3.6 KiB Raw Blame History