TIA Undistort

TIA Undistort is a command-line utility designed for Atari 2600 homebrew developers. It pre-processes audio samples to compensate for the non-linear mixing characteristics of the TIA (Television Interface Adapter) chip.

By "undistorting" the audio data before it reaches the hardware, you can achieve significantly clearer PCM playback on the Atari 2600.

📉 The Problem

The Atari 2600 TIA chip does not mix audio channels linearly. When combining volumes from two channels (or driving a single channel against the chip's impedance), the output volume follows a curve rather than a straight line.

The mixing formula is approximately:

$$ V_{out} = \frac{V_{in}}{M} \times \frac{30 + M}{30 + V_{in}} $$

Where:

• $V_{out}$ is the resulting output volume (0.0 to 1.0).
• $V_{in}$ is the combined value written to the volume registers (0 to $M$).
• $M$ is the maximum theoretical volume (typically 15 for one channel, or 30 for combined channels).

If you play linear PCM samples directly through the TIA, the non-linear response compresses louder sounds and distorts the waveform.

🚀 The Solution

TIA Undistort analyzes your source audio and applies the inverse of the TIA's mixing function. It calculates exactly what value must be written to the TIA registers to achieve the desired linear output.

The result is a pre-distorted sample that, when run through the TIA's non-linear hardware, sounds linear to the human ear.

✨ Features

• Inverse Curve Mapping: Mathematically perfect inversion of the TIA mixing circuit.
• High-Quality Resampling: Uses libsamplerate (Secret Rabbit Code) to resample audio to your target frequency (e.g., 15.720 kHz) with proper anti-aliasing filters.
• Extended Resolution Mode (-x): Support for 5/76 cycle PWM kernels, treating the Atari as a 256-level non-linear DAC.
• Automatic Normalization: Normalizes input to 0dB to utilize the full bit-depth resolution of the TIA registers.
• Flexible Output:
  • RAW: Unsigned 8-bit (0-255), ready for inclusion in ASM projects.
  • WAV: 32-bit Float WAV, representing the control data (pre-distorted), suitable for further processing chains (like ADPCM encoding).

🛠️ Building & Installation

Dependencies

This tool relies on standard audio libraries:

• libsndfile (for reading/writing audio files)
• libsamplerate (for high-quality resampling)

Ubuntu/Debian:

sudo apt-get install libsndfile1-dev libsamplerate0-dev

macOS (Homebrew):

brew install libsndfile libsamplerate

Compilation

You can compile the tool using gcc:

gcc -o tia_undistort tia_undistort.c -lsndfile -lsamplerate -lm

📖 Usage

./tia_undistort -i <input_file> -o <output_file> [options]

Options

Flag	Description
-i	Input file. Supports WAV, OGG, FLAC, etc.
-o	Output file.
-r	Target Sample Rate (Hz). Resamples input using high-quality sinc interpolation. Useful for matching scanline frequencies (e.g., 15720).
-m	Max Volume (15 or 30). Default is 30. Use 15 if your playback routine only uses AUDV0. Use 30 if you sum AUDV0 + AUDV1. Ignored if -x is used.
-x	Extended Resolution Mode. Enables logic for PWM kernels (see below).
-f	Output Format (raw or wav). Default is raw.

Extended Resolution Mode (-x)

This mode supports advanced playback kernels that utilize pulse-width modulation to increase bit depth. Specifically, it targets kernels where:

1. AUDV0 is held for the full scanline (76 cycles).
2. AUDV1 is held for ~5 cycles, and then zeroed for ~71 cycles.

Because the TIA is non-linear, you cannot simply treat AUDV1 as a linear "fractional" addition. TIA Undistort solves this by generating a palette of all 256 possible physical states, sorting them by effective voltage, and mapping your audio to the closest physical match.

Output in this mode:

• High Nibble: AUDV0 value.
• Low Nibble: AUDV1 value.

Examples

1. Prepare a sample for a 1-line kernel (approx 15.7kHz) using standard combined voices:

./tia_undistort -i music.wav -o music_tia.raw -r 15720 -m 30

2. Prepare a high-quality sample using the PWM technique (-x):

./tia_undistort -i speech.wav -o speech_pwm.raw -r 15720 -x

3. Output a WAV file for further processing (e.g., ADPCM encoding):

./tia_undistort -i kick.wav -o kick_pre_distorted.wav -x -f wav

📦 Output Formats

• RAW (-f raw): The output is Unsigned 8-bit PCM (0-255).

  • This is the binary data intended to be included directly in your ASM code.

• WAV (-f wav): The output is 32-bit Floating Point WAV.

  • Important: This WAV file represents the Control Data, NOT the simulated sound. The intent is you can feed the WAV file to another utility that performs some final pre-encoding step. It's crucial you don't do any operation on the WAV file that would alter it's levels, like filtering, normilisation, eq, etc.
  • If you view this WAV in an editor, it will look distorted (bent curves, quantization noise). This is intentional.
  • It represents the exact values (normalized 0.0-1.0) that must be fed to the hardware to produce a linear sound. Use this format if you need to pass the data to another tool (like a packer or compressor) before final conversion to binary.