# FloppyDisQ User Manual

**Version 0.22.4 | Engineer test edition | 21 October 2026**

FloppyDisQ is a 16-layer software sampler for playing, capturing, editing, and mapping your own sounds inside a DAW. It is supplied as an Audio Unit and VST3 plug-in on macOS. The DAW provides sequencing and transport; FloppyDisQ is an instrument plug-in, not a standalone app. This manual describes the 0.22.4 engineer test build. See TIME_ENGINE.md for the live stretching controls and performance limits.

## 1. Start here

### Install in Logic Pro on a Mac

1. Quit Logic Pro.
2. Copy `FloppyDisQ.component` from the test package to `~/Library/Audio/Plug-Ins/Components/`.
3. Restart Logic. Create a Software Instrument track and choose **FloppyDisQ** from **AU Instruments**.
4. If it is missing, open Logic's **Plug-in Manager** and rescan it. If Logic marks it **[Incompatible]**, send the validation report to the developer; entering a key will not repair an AU validation failure.

For a Mac VST3 host, copy `FloppyDisQ.vst3` to `~/Library/Audio/Plug-Ins/VST3/`, then restart or rescan the host. The bundle contains Apple Silicon and Intel slices, but the Intel slice still needs a DAW test on an Intel Mac. Windows and Linux builds remain development targets and have not passed host testing for this version.

The engineer build is ad hoc signed and has not been notarized. If another Mac blocks it, send the exact message to the developer. Keep the supplied license key within the invited test group.

### Activate the tester license

1. Open the supplied `FloppyDisQ-Test.key` file in a text editor and copy its complete `FDQ1-...` line.
2. Open FloppyDisQ's **SETUP** page and click **ENTER KEY**.
3. Click the large key box to paste, then click **ACTIVATE**. The key box also accepts typing when the host forwards keyboard events.
4. Check the UTC expiration displayed on SETUP. The test package's `KEY_EXPIRY.txt` gives the exact date.

If a DAW does not pass clipboard input, copy the key file to `~/Library/Application Support/FloppyDisQ/license.key` and reopen the editor. The AU and VST3 read the same key from your user account. A replacement key can be entered later without changing your project. An expired or missing key silences playback and locks editing; the project state remains saved.

### Make your first instrument

1. Select layer **01** with the first button in the lower layer row.
2. Open **LOAD**, choose **LOAD FILE**, and select a WAV.
3. Play the on-screen keyboard or send MIDI from your DAW.
4. Open **LAYER > MAP**, choose **SET KEYS**, and play the two keys that should bound the layer's range.
5. Open **WAVE** and try **FWD LOOP** while holding a note. Drag **PLAYHEAD** to move through the sample live.
6. Save your DAW project. Keep the source WAV in its current location so the project can find it later.

## 2. The front panel

The top row selects the eight pages: **LOAD, WAVE, EDIT, ENV, TONE, LAYER, SETUP, SAMPLE**. The LCD below it contains text choices and pixel-style sliders. A value grows while you drag its slider. The lower row has eight physical buttons with two LEDs per button: the left LED selects the first layer in a pair, the right LED selects the second. Together they select layers 01-16. The illuminated LED shows the active layer.

The 61-key keyboard lets you audition sounds and enter map boundaries. Keys also light while notes from an external MIDI keyboard are held on the track. **HIDE KEYS / SHOW KEYS** collapses it; **HIDE MAP / SHOW MAP** independently collapses the layer-range readout below. The range readout shows each layer's key span and detected BPM where available. The floppy-drive light flashes when you select a control. The drive's eject button opens Navi's panel.

On a Mac, the keyboard header starts in **MIDI PREVIEW**. Clicking a key plays the sampler directly in this mode, so that click is not a recordable Logic MIDI input. To record these clicks, click **MIDI PREVIEW** to switch to **MIDI TO DAW**, select and record-enable the FloppyDisQ software instrument track in Logic, and record. This mode sends clicks from a CoreMIDI source named **FloppyDisQ Keys** into the DAW; Logic must monitor or record that source to hear the notes. If your track has a specific MIDI input port selected, choose **FloppyDisQ Keys**. Click the legend again to return to direct preview. The MIDI mode is a session setting and starts in PREVIEW when the editor reopens.

**Selected layer rule:** LOAD, EDIT, ENV, TONE, LAYER MAP, and SAMPLE act on the selected layer unless stated otherwise. The **WAVE loop-mode choice is currently a global override for all layers**. WAVE playhead movement and EDIT sample/loop bounds apply to the selected layer. Choosing **FILE** on WAVE restores each loaded zone's own mode.

## 3. LOAD and WAVE

### LOAD: bring in a sample

**LOAD FILE** opens a file chooser for the selected layer. WAV import supports mono or stereo 16-, 24-, and 32-bit PCM and 32-bit float audio, with a 64 MiB decoded-audio limit. A new empty project plays an internal init tone until a file is loaded. An experimental EFE/EFA instrument can be loaded in layer 01; direct EDA disk browsing is unavailable. EFE/EFA conversion is incomplete, so use WAV for the most predictable editing workflow.

### WAVE: perform the loop

Choose **PLAY** for the waveform preview, live playhead bar and loop modes. **GENERATE** creates one SINE,
SQUARE, or SAW sample in the selected layer. Pick a shape and press
**GENERATE TO LAYER**. FloppyDisQ writes an eight-second mono 48 kHz C4 WAV
to `~/Music/FloppyDisQ/Generated/`, sets its root to C4, and loads it. The
prior source stays on disk. Use a looping mode to sustain the tone.

Hold a key while choosing a loop mode to hear the change. Use **EDIT > TRIM/NORM** for playhead seeking and sample/loop start/end points. LOAD and WAVE → PLAY provide previews without duplicate playhead sliders. WAVE → PLAY has a blue position marker on the waveform that follows the newest triggered voice, in one-shot and looping modes. After a one-shot finishes, its final position stays visible until a new note, seek, bounds change or panic. Very short hits may finish between display refreshes; their endpoint remains visible. EDIT → TIME ENGINE provides independent live speed/pitch and DAW tempo sync; see TIME_ENGINE.md.

| Choice | Playback |
| --- | --- |
| FILE | Use the loaded zone's saved mode, including supported WAV smpl loops; WAVs without loop metadata start forward. |
| OFF | Play forward once from sample start to sample end. |
| FWD LOOP | Play forward; repeat from loop end to loop start. |
| REV LOOP | Repeat the selected loop backward. |
| BI-DIR | Play into the loop, then alternate forward and backward. |
| LOOP+REL | Loop while the key is held; after release, continue forward into material after the loop. The amp release can fade before a long tail finishes. |
| REV ONCE | Play once backward from sample end to sample start. |

**Looping tip:** set sample start before the attack you want, and place loop start after the attack. Use **LAYER > SLIDE > XFADE** to crossfade across the loop seam on the selected layer. It fades over up to 25% of the loop length in forward or reverse looping; 0% bypasses it. Bidirectional loops do not use this crossfade. EDIT > TRIM/NORM offers optional SNAP to nearby zero crossings. The WAVE mode selector remains global.

## 4. EDIT: trim, normalize, time engine, and chop

Choose a layer before editing it. The waveform shows its current sample and loop markers. The playhead follows a sounding voice unless you are dragging the playhead control.

### TRIM/NORM

The five rails are **PLAYHEAD**, **SAMPLE START**, **SAMPLE END**, **LOOP START**, and **LOOP END**. The latter four define a region for this layer while it plays. Move them while auditioning. **ROOT KEY** is also available here.

**TRUNCATE** writes the region between SAMPLE START and SAMPLE END to a new 32-bit float WAV, loads that copy into the selected layer, and resets its bounds to the full new file. **NORMALIZE** peak-normalizes the selected WAV file to 0.99 peak and loads a new copy. Normalization processes the file currently loaded in the layer; truncate first if you want to normalize only a chosen region. Both operations keep the source WAV untouched. New files go to `~/Music/FloppyDisQ/Edits/` on macOS.

### TIME ENGINE

Choose CLASSIC, STRETCH or SYNC for the selected layer. STRETCH separates speed and pitch; SYNC follows DAW tempo from source BPM or musical length. See TIME_ENGINE.md for all controls, quality/latency and the eight/sixteen-voice limit.

### CHOP

**AUTOCHOP** detects attacks, creates separate WAV slices, and maps them to consecutive MIDI keys. It starts at the selected layer, then uses empty layers. The first slice replaces the selected layer's loaded reference; the original WAV stays on disk. The current layer's low key supplies the first key, or MIDI 36 when the low key is zero. Leave enough empty layers and keys for the number of slices you want. Generated files go to `~/Music/FloppyDisQ/Edits/`.

### Precise points and background edits

TRIM/NORM has five separated point rails. Click a value to type an exact position, such as `24000 samples`, `250 ms`, `1.5 s`, or `25%`, then press Enter. Hold Shift while dragging for finer changes. ZOOM cycles 1x to 16x; the adjacent arrows move the waveform view. SNAP moves released sample/loop boundaries to a nearby zero crossing. Root AUTO and typed root entry remain at the upper right. Normalize, truncate, and chop run in a background worker with progress and CANCEL; cancelling leaves layer audio unchanged. The original WAV is retained.

## 5. LAYER: map and mix sixteen sounds

### MAP

Use **LOAD** to replace the selected layer's sample, **RENAME** to change its displayed name, and **CLEAR** to empty it. To copy any WAV layer, select it and press **COPY**. The LCD shows sixteen separate destination choices, including every even-numbered layer. Select the target, then press **PASTE**. Selecting a target does not change its audio until PASTE. **CANCEL**, Escape, or leaving the page cancels the operation. Copy carries sample/loop bounds, root pitch, BPM and sound/mixer settings; the target keeps its key and velocity range. **UNDO** restores replaced audio. EFE/EFA sources remain restricted to layer 1.

Choose **SET KEYS**, then play the two ends of the desired range on the on-screen or MIDI keyboard; either order works. Drag the paired key and velocity sliders for finer control. **AUTO** at ROOT KEY makes the mapped low key play at the sample's original pitch. To enter a root manually, click its note box and type a note such as `C4` or `F#3`, a MIDI number such as `60`, or `FILE` to restore file tuning. Manual entry turns AUTO off. The layer-range strip beneath the keyboard shows every layer's range.

### MIX 01-08 and MIX 09-16

Each view shows eight channels. Drag **VOL** for layer level and **PAN** for its stereo position. VOL is the same layer gain available on TONE > FILTER; changing either changes the same value. Click **CUT** to cycle OFF and groups 1-8.

When a new note triggers a layer in a CUT group, older sounding voices in that group stop. Layers triggered by the same new note can still sound together. Put an open and closed hi-hat in the same group to have the closed hat stop the older open hat. **CUT OFF** leaves a layer independent. CUT groups do not delete audio or change key maps.

### SLIDE

Select a layer with a track button, then tap **A** or **B** to assign it to the crossfade pair. Turn **SLIDE ON** and drag the rail from A to B. The endpoints play one chosen layer at full level; the center uses an equal-power blend. Other layers keep their usual mixer levels. Turn SLIDE OFF to hear the normal layer mix. Assign two different layers, with overlapping key and velocity maps, if you want both to respond to the same MIDI note.

### XFADE under SLIDE

Below the A/B slide rail, drag **XFADE** to blend the end and start of a forward or reverse loop. The control belongs to the selected layer and is measured as a percentage of that layer's loop length. Hold a note while adjusting it to audition the seam. Set it back to 0% when the loop already joins cleanly.

## 6. ENV and TONE: shape each layer

**ENV** has amplitude **ATTACK, DECAY, SUSTAIN, RELEASE** rails for the selected layer. Short attack and release values suit sharp hits; longer values make the sound fade in and out.

**TONE > FILTER** offers LOW PASS, HIGH PASS, and MID ISOLATE with two- or three-pole choices. CUTOFF / MID positions the filter, MID WIDTH sets the span of the isolated band, and OUTPUT GAIN sets the selected layer's level. **TONE > LO-FI** reduces sample rate and bit depth on that layer before mixing; OFF bypasses each reduction. **TONE > LFO** offers SINE, SQUARE, and SAW waves with RATE and DEPTH and a PITCH, FILTER, AMP, or OFF target. Each layer keeps its own ENV, TONE, LO-FI, and LFO settings.

## 7. SAMPLE: capture computer playback

FloppyDisQ captures the Mac's computer playback through ScreenCaptureKit rather than recording a microphone into the instrument. Select the destination layer before starting. Open **SAMPLE**, choose **START CAPTURE**, play the sound you want to record, then choose **STOP & LOAD**. The display shows elapsed recording time, a finishing state, and then a saved or error result. The recorded WAV loads into the destination layer. A take stops after 30 seconds. The file is stored in `~/Music/FloppyDisQ/Recordings/`.

### AI GENERATE (Mac prototype)

Open **SAMPLE > AI GENERATE > OPEN AI SAMPLE**, even if the selected layer is empty. Choose **Describe only** to make a sample from a text prompt, or load a WAV and choose **Use layer audio** to generate a variation based on it. Type a description, choose 8, 16, or 30 seconds, and enter your Stability AI API key. Variation strength applies only to Use layer audio. **Generate** sends the prompt to Stability AI; Use layer audio also uploads a copy of the WAV. Use only audio you have permission to upload. FloppyDisQ repeats source WAVs shorter than six seconds to meet the audio-to-audio service's minimum input length.

When the candidate arrives, **Audition** plays it through the Mac's audio output. **Keep on Layer** loads it into the target layer and resets that layer's playhead, sample start/end, and loop start/end to 0/100% for the new WAV; **Discard** deletes the candidate. **Reveal WAV in Finder** shows a saved candidate for dragging to an audio track. The prior WAV remains on disk and the layer does not change until Keep. Close the window to clear the API key from its field. Provider credits and an internet connection are required. Audio-to-audio generation and audition worked in Logic. Both mode choices and generated-sample edit bounds were user-confirmed. A new live text-only provider generation remains to be checked. KEEP now commits a durable audio copy before importing it; closing or cancelling while the brief commit runs is disabled so that retained samples cannot be deleted. Windows and Linux do not yet have the generation window. Generated candidates are limited to 30 seconds and 16 MB.

If generation fails, the message identifies an HTTP response, DNS issue, TLS issue, timeout, or a DAW connection block. The Mac request uses the system HTTPS client; the key remains in memory for the window session and is not written into command arguments or a file.

macOS may ask for Screen Recording access for system-audio capture. Grant it to the host when prompted, then retry if the first attempt fails. Capture uses the computer's default playback output; this build has no input-device picker, threshold trigger, or monitoring controls. Check that no unintended private audio is playing before capture.

## 8. SETUP and Navi

**SETUP > SYSTEM** selects a 32- or 23-voice budget, provides GLOBAL ROOT, and shows license status. GLOBAL ROOT overrides all layers, including their manual and AUTO roots, while set to a note. Return it to FILE to use the individual roots saved on LAYER or EDIT. These voice limits do not force a hardware sample rate; stretched playback has its own eight/sixteen-voice safety limit described in TIME_ENGINE.md.

**SETUP > ASSIST** manages Navi's local control link. Clicking the floppy-drive eject button also opens Navi's panel and turns on the link. With the local **Navi for FloppyDisQ** tool installed in ChatGPT Work, you can request bounded actions such as selecting a layer, changing its settings or key map, moving sample bounds, stretching/chopping a WAV, or starting/stopping a capture. The local MCP server also works with Claude and other MCP clients. Navi's staff-hit pose signals a completed action. The link works only while an editor window is open and the link is on.

The bridge passes parameter values, layer names, maps, and sample filenames, not audio or full file paths. It cannot hear a sample or judge its sound. **OPEN WORK APP** opens the desktop app but does not install the tool. **API CHAT** opens a native plug-in chat window on macOS: choose OpenAI or Claude, enter a model ID and your own API key, then send a request. **Check Link** checks the local control bridge without a provider call. The chat is pinned to the plug-in instance that opened it, accepts one task at a time, and has STOP for cancelling a request. Provider changes and closing the window clear its key field. The key is hidden and held only for that session; it is not saved in the DAW project. Your requests and sampler metadata go to the provider you choose. Python 3 and internet access are required for API CHAT; the plug-in's audio engine does not call the network. Spoken requests still use Voice in a connected ChatGPT Work chat. The tester package contains `assistant-plugin/install_local.py`, `assistant-plugin/navi_chat.py`, and `docs/ASSISTANT.md` for setup. Public distribution of the Work desktop integration needs separate approval.

## 9. Projects, files, and automation

Save your DAW project to retain layer paths, names, maps, sample positions, sound settings, mixer settings, and CUT groups. For a portable copy, choose **LOAD > SAVE + SAMPLES** and save a `.fdq` instrument. It creates a sibling sample folder and stores relative references; move the instrument and that folder together. **OPEN INSTRUMENT** restores it. A normal DAW project still references external audio paths. If a path is missing, select its layer and use **LOAD > RELINK LAYER**; relinking preserves its edit settings. Originals and generated files remain in place. A failed replacement keeps the prior playable sample.

The AU/VST3 exposes parameters for host automation, including layer volume, pan, and CUT group. Automation of live controls can be musical, but very fast changes to a playhead or loop boundary may create abrupt audio jumps. Save a copy of the DAW project before extensive automation or destructive project changes. The edit commands create new files. **UNDO** and **REDO** above the layer row, or Command/Ctrl-Z and Shift-Command/Ctrl-Z when the host forwards them, restore up to 32 editor states. This history lasts while the editor is open and covers parameter drags and layer/file changes. Capture and a running background edit must finish before undo.

## 10. Troubleshooting

| Symptom | Check |
| --- | --- |
| No sound | Confirm the license is valid, the track receives MIDI, the selected layer has a WAV or the init tone, the note falls inside its key/velocity map, and layer volume is above zero. Check CUT groups if notes stop unexpectedly. |
| Plug-in absent in Logic | Restart Logic and rescan in Plug-in Manager. Confirm one current `FloppyDisQ.component` is installed in the user Components folder. |
| Logic shows [Incompatible] | Send the Plug-in Manager validation report and the macOS/Logic versions to the developer. A license key cannot fix validation. |
| Project opens with missing audio | Restore the original WAV paths or the generated WAVs from Edits/Recordings. The project stores references, not audio data. |
| Sample capture fails | Check Screen Recording access for the DAW, confirm computer playback is audible through the default output, and retry a short take. |
| Loop clicks | Move loop start/end to a quieter or more similar part of the waveform, then try LAYER > SLIDE > XFADE for forward or reverse loops. |
| Headphone unplug closes the editor | If Logic reports that its previous audio interface is unavailable, select **System Setting** as Logic's Output Device, apply, and reopen the plug-in window from its instrument slot. Confirm the instrument remains in the slot and retains its settings. |
| Navi cannot change a parameter | Keep the editor open, turn the control link on, and connect Work, Claude, another MCP client, or API CHAT. Navi has no access to raw audio. |

For a useful test report, include your macOS and DAW versions, the sample format and rate, exact steps, expected behavior, actual behavior, and a short audio example or screenshot if relevant. Keep license tokens out of screenshots.

## 11. Current scope

This is an independent sampler inspired by hardware workflow. It does not boot the original operating system or emulate proprietary chips or effects. Direct EDA disk browsing, complete EFE/EFA conversion, automatic loop finding, real-time time stretch, in-plug-in voice chat, a standalone app, and an internal sequencer are outside version 0.21.0. Reference-based AI generation is a Mac prototype, with live provider and Windows/Linux checks still pending. External DAW validation, signing/notarization, and more listening tests remain before a public commercial release.

**FloppyDisQ 0.21.0 - Engineer test edition.** The AU editor dispatches
render-thread parameter notifications to its main-thread UI timer. The
version 0.19 crash reported by an engineer has not been reproduced or
symbolicated without its original crash file; repeat that workflow on the
same system before treating it as resolved.