# Task: Diagnose and Fix Unwanted Audio Artifacts in AY/YM Music Playback

## Objective

Investigate and correct unwanted audio artifacts in music played through an AY-3-8910, AY-3-8912, YM2149, or compatible PSG sound chip.

Two types of problems have been observed:

1. **Unwanted white-noise bursts at the beginning of certain instrument sounds**, sometimes resembling a brief hiss, click, or noisy attack.
2. **Discordant or unpleasant sounds at the end of certain notes**, including unexpected pitches, buzzing, residual tones, or abrupt changes in timbre.

These artifacts may be intermittent, instrument-specific, or dependent on the preceding notes or sound effects.

The goal is to identify and eliminate the underlying technical causes while preserving the intended musical arrangement and instrument characteristics.

## 1. Investigate Before Modifying

Do not assume that the instrument definitions or music data are responsible.

First determine whether the artifacts originate from:

- The original instrument or music data.
- The music player or sound engine.
- Incorrect PSG register initialization.
- Register values persisting between notes or instruments.
- Incorrect ordering or timing of PSG register writes.
- Interactions between tone, noise, and hardware envelopes.
- Interrupt timing or playback synchronization.
- Conflicts between music and sound effects.
- Differences between emulator behavior and real hardware.

Whenever possible, compare the original music data with the actual PSG register writes generated during playback.

Distinguish intentional instrument effects from unintended artifacts.

## 2. Examine the AY/YM Registers

Pay particular attention to:

| Registers | Function | Potential problems |
|---|---|---|
| R0–R5 | Tone periods for channels A, B, C | Incorrect or stale pitch values |
| R6 | Shared noise period | Unexpected noise characteristics |
| R7 | Tone and noise mixer enables | Accidental noise activation or unwanted tone |
| R8–R10 | Channel volumes and envelope selection | Incorrect volume or envelope transitions |
| R11–R12 | Shared hardware envelope period | Unintended envelope frequency |
| R13 | Hardware envelope shape | Unexpected envelope restart or shape changes |

Remember that the AY/YM has shared hardware resources. Changes intended for one channel can affect another.

In particular, investigate whether unwanted noise bursts result from the noise generator being enabled before the correct mixer, period, and volume states have been established.

Also investigate whether discordant note endings result from stale tone periods, unintended mixer changes, or hardware-envelope interactions.

Treat these as hypotheses to verify, not predetermined explanations.

## 3. Capture and Analyze Playback

Where technically possible:

1. Identify a reproducible occurrence of each artifact.
2. Capture the PSG register writes immediately before, during, and after the affected note.
3. Compare the register sequence with a clean occurrence of the same instrument.
4. Examine the order of register updates within each playback tick.
5. Determine whether the issue depends on the preceding instrument, note, channel, or sound effect.
6. Identify the smallest code or data change that addresses the root cause.

If the issue is intermittent, investigate initialization and state-dependent behavior rather than applying arbitrary timing adjustments.

## 4. Apply Minimal, Targeted Corrections

Depending on the confirmed cause, appropriate fixes may include:

- Correcting unintended noise-generator activation.
- Ensuring tone and noise periods are initialized before they become audible.
- Correcting the order of PSG register writes.
- Resetting or restoring stale register state when necessary.
- Fixing incorrect instrument initialization or release handling.
- Preventing unwanted interactions between channels or sound effects.
- Correcting unintended hardware-envelope retriggering.

**Do not automatically modify instrument definitions to compensate for a player bug.**

Avoid broad changes to the sound engine when a localized correction is sufficient.

## 5. Preserve Musical Integrity

The corrections must preserve:

- All notes and pitches.
- Instrument identities and their intended timbres.
- Musical tempo and rhythm.
- Pattern order and repetitions.
- Note lengths and intentional silences.
- Intended vibrato, arpeggios, pitch effects, and envelopes.
- Deliberate noise-based percussion and sound effects.
- Overall synchronization and musical expression.

Do not introduce artificial fades, filtering, shortened notes, muted attacks, or additional silences merely to conceal an artifact.

If the original instrument data genuinely contains the unwanted behavior, explain the evidence and propose the smallest possible modification before changing it.

## 6. Validation

For each correction:

- Confirm that the original artifact is eliminated.
- Compare PSG register traces before and after the change.
- Check all occurrences of the affected instrument.
- Verify that other instruments and channels remain unchanged.
- Test transitions between notes, patterns, and songs.
- Check for regressions in percussion, noise effects, and hardware envelopes.
- Compare emulator and real-hardware playback where available.

Do not claim that an issue has been fixed unless the relevant test has actually been performed.

## 7. Expected Output

Provide:

1. **Diagnosis:** The identified or most likely cause of each artifact.
2. **Evidence:** Relevant PSG register sequences, timing observations, or comparisons.
3. **Correction:** The precise code or data changes required.
4. **Musical impact:** Confirmation of what remains unchanged.
5. **Validation:** Tests performed, results, and remaining uncertainties.

If the available evidence is insufficient, clearly identify what additional recordings, source files, register traces, or playback information would be needed.

## Priority

Address the unwanted noise bursts at instrument onset first, followed by discordant note endings.

**Most importantly: establish whether the problem comes from the music data or from how the PSG is being driven before changing the composition or instrument definitions.**