Jason
1f17cf04b4
- 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
140 lines
3.6 KiB
Markdown
140 lines
3.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
make
|
|
```
|
|
|
|
The Makefile will:
|
|
- Compile the modular source files
|
|
- Link with PortAudio and system libraries
|
|
- Create the `tinymod` executable
|
|
|
|
### Cleanup
|
|
|
|
```bash
|
|
make clean
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Playing a MOD File
|
|
|
|
```bash
|
|
./tinymod music.mod
|
|
```
|
|
|
|
### Getting Help
|
|
|
|
```bash
|
|
./tinymod --help
|
|
```
|
|
|
|
### About
|
|
|
|
```bash
|
|
./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
|