# Crash BASIC 1.52.0 Release Notes

*~written by Crash-tan~*

## PUT A RECORDING IN YOUR SONG

Songs have always been made of notes. Now a pattern can hold a **recording** —
an MP3 or WAV you loaded, mixed in as part of the song rather than played
alongside it.

```basic
LOADMP3 "vocals.mp3", "vox"

MUSIC "anthem"
  PATTERN "chorus"
    AUDIO "vox" VOLUME 85
    TRACK CHANNEL(1) INSTRUMENT(12) NOTES "o4 c e g"
  END PATTERN
  ARRANGEMENT
    PLAY "chorus"
  END ARRANGEMENT
END MUSIC

PLAYMUSIC "anthem"
```

A pattern can hold tracks, a recording, or both — so a live vocal take can sit
under a chiptune arrangement, a recorded drum loop can carry a synth melody, or
a whole pattern can be nothing but a pre-recorded section. `WITH` in the
arrangement still layers patterns, so a recording in one pattern can run under
an entirely different one.

The recording is mixed into the song when the song renders, not started
separately when it plays. That is the part that matters: it stays locked to the
notes, including across a loop, with no drift and no seam.

## FOUR WAYS TO PLACE IT

`AUDIO` takes the same kind of modifiers a `TRACK` does, in any order:

```basic
AUDIO "take" SECTION(8, 24) OFFSET 0.25 VOLUME 60 PAN -0.3
AUDIO "break" REPEAT
```

- **`VOLUME`** and **`PAN`** sit it in the mix, 0–100 and -1.0 to 1.0.
- **`SECTION(start, end)`** mixes only part of the file, in seconds — one long
  recording can supply an intro pattern and a verse pattern without being cut
  into separate files.
- **`REPEAT`** tiles a short clip to fill the pattern, the way a `REPEAT` track
  tiles its notes. A two-bar recorded loop under an eight-bar pattern.
- **`OFFSET`** starts it partway into the pattern, so a recording can enter late
  without silence baked into the file.

An audio pattern is as long as its clip, rounded up to a whole bar — so however
long the recording happens to be, whatever plays after it still lands on a
downbeat.

## THE HANDLE IS THE POINT

`AUDIO` names a **handle**, not a filename — the handle you gave `LOADMP3` or
`LOADWAV`. So the recording behind a song is something you can change without
touching the song:

```basic
LOADMP3 "day_theme.mp3", "bed"
PLAYMUSIC "level"

' ...night falls
LOADMP3 "night_theme.mp3", "bed"    ' same handle, different file
PLAYMUSIC "level"                    ' same song, new recording
```

One song, one arrangement, and the backing track swaps under it. The same works
from a `.cbm` file written in the Music Editor: the bank names handles, your
game loads whatever it wants on them, and nothing is baked into the file. It
also means a `.cbm` stays small — no audio is stored in the bank.

Load your clips before `LOADMUSIC` or `PLAYMUSIC`. A pattern naming a handle
nothing was loaded onto is a clear error that names the handle, rather than a
song that quietly comes out missing its backing track.

## THE PITCH WHEEL REACHES A NOTE THAT IS ALREADY PLAYING

Bending a note used to be something you decided when the note started — MML's
`~` and `&` set a slide at the moment the note is struck, and that was the only
way to bend anything.

The synth can now bend notes that are **already sounding**. That is what a pitch
wheel needs: you hold a key, and the bend arrives afterwards, continuously, for
as long as you keep moving the wheel.

It behaves the way a wheel does rather than the way a note does:

- **One wheel bends everything you are holding.** Bend is per channel, so a held
  chord bends as a chord, in tune with itself.
- **The wheel reports a position, not a nudge.** The bend is measured from the
  pitch each note was struck at, so centring the wheel returns to the original
  pitch — there is no drift from accumulated messages.
- **It glides from wherever the pitch actually is.** A controller sends dozens of
  messages a second; each one continues from the pitch currently sounding
  instead of snapping back to the struck note and starting over. That difference
  is audible — the naive version stutters.
- **Notes still ringing after key-up follow it too**, so a bend through a release
  tail sounds like one gesture rather than stopping at the key.

This is engine support: the runtime accepts and performs the bend, and the
editors will hand it your MIDI controller's wheel. Nothing in Crash BASIC
changes, and MML's own `~` and `&` are untouched.

## ALSO IN THIS RELEASE

**Loading a different file onto a live handle works again.** Since 1.47.0,
`LOADMP3 "boss.mp3", "music"` over a handle already holding `title.mp3` did
nothing at all — the first file stayed, and nothing said so. That came from a
guard added to stop a `LOADMP3` in a game loop from re-decoding the same file
every frame and leaking a copy of the audio until phones ran out of memory. The
guard only asked whether *something* was loaded under that name, never whether
it was the *same file*, so it couldn't tell a wasteful repeat from a deliberate
swap. It now asks both: re-loading the same file is still free, and loading a
different one swaps the clip and releases the old audio. Both `LOADMP3` and
`LOADWAV`, everywhere Crash BASIC runs — and it is what makes the handle swap
above possible.
