Ferrett Audio Tools

A REAPER production toolkit for a basement hip-hop / blues workflow: AI stem separation, Fadr MIDI/chord extraction, full session auto-building, tone chains for guitar/bass/vocals/drums built from a real owned-gear inventory, MIDI cleanup for AI-generated parts, generative composition tools, and render/QA scripts to close out a mix.

Everything here works off whatever track/item/file is currently selected in REAPER — nothing is hardcoded to one song, with the deliberate exceptions noted under Top-level pipeline files.

Browsing without cloning: the companion app ferrett-studio-os has a searchable "SCRIPT DB" panel listing every file below with a one-click download, if you just want one script instead of the whole repo.

Contents

• Requirements
• Installing a script into REAPER
• Typical end-to-end workflow
• Repo layout
• Top-level pipeline files
• Lua/Pipeline_UVR_Fadr — stem separation & Fadr import
• Lua/Project_Setup — session & arrangement scaffolding
• Lua/Bus_Builders
• Lua/Vocal_Chains
• Lua/Guitar_Bass_Tone
• Lua/Trash_and_Echo_FX
• Lua/MIDI_Cleanup
• Lua/Sampling_and_MIDI_Generation
• Lua/Stem_Workflow_QA
• Lua/Rendering_QA
• Lua/Reference_Tools
• Shell_Scripts
• Track_Templates
• MIDI/Basement_Drum_Grooves_20
• Docs
• Retired / Superseded

Requirements

• REAPER, with your Action List reachable (Actions → Show Action List).
• ReaImGui (install via ReaPack: Extensions → ReaPack → Browse Packages → search "ReaImGui") — required by the five GUI tools in Lua/Sampling_and_MIDI_Generation/ (files 1_ through 5_).
• Python 3 with the audio-separator package and friends, for auto_uvr.py. On this machine that's the uvr-env-311 virtualenv; adjust the PYTHON path in run_uvr_pipeline.command if yours lives elsewhere.
• The tone-chain scripts assume specific owned plugins (UAD, kHs, NAM/Gateway captures, etc.) — see Docs/Gear_Inventory/OWNED_INVENTORY.txt for the full list they're built against.

Installing a script into REAPER

1. Actions → Show Action List → New Action → Load ReaScript... → point it at the .lua file. Repeat per script, or drop the whole Lua/ folder into REAPER's own Scripts/ folder and use Actions → Rescan to pick up everything at once.
2. Optional: assign a keyboard shortcut in the Action List (a few scripts below list the shortcut they were built around, e.g. Ctrl+Shift+U).
3. GUI tools (the five N_..._gui.lua files) open an ReaImGui window when run — no extra setup beyond having ReaImGui installed.
4. run_uvr_pipeline.command and the two Shell_Scripts/*.sh/*.zsh files aren't ReaScripts — they're launched from Finder/Terminal, not REAPER's Action List (details in their own sections).
5. .RTrackTemplate files go through REAPER's own template picker (Track → Track Templates → Insert Track from Template), not the Action List.

Typical end-to-end workflow

1. Make a folder at ~/Documents/Music Projects/<Song Name>/ and drop the master WAV in it.
2. Run the UVR separation pipeline on that WAV — either Split-Audio.lua from inside REAPER, or double-click run_uvr_pipeline.command. Stems land in Stems/UVR/ inside the song folder automatically.
3. Optionally run Fadr_MIDI_Extract_v6_LastUsed.lua on a part you want as MIDI, and/or Fadr_Chord_Mapper.lua for chord detection.
4. In REAPER, run Autoproject_setup_master.lua on the song folder — it scans for every stem and Fadr file it can find and builds the full routed session (buses, sends, FX chains) around them.
5. Layer in tone chains (Lua/Guitar_Bass_Tone, Lua/Vocal_Chains), clean up AI MIDI (Lua/MIDI_Cleanup), triage/QA the stems (Lua/Stem_Workflow_QA), generate extra parts (Lua/Sampling_and_MIDI_Generation), and finish with Lua/Rendering_QA.
6. Save the .rpp inside that same song folder.

Repo layout

auto_uvr.py                    UVR extraction GUI (Vocals / Instrumental+Drums / Full pipeline)
fadr_cloud.py                  Fadr cloud MIDI-extraction backend, called by Fadr_MIDI_Extract
Split-Audio.lua                REAPER-side trigger for auto_uvr.py
run_uvr_pipeline.command       double-clickable Terminal launcher for auto_uvr.py
UVR_Models/                    persistent local model cache (BS-Roformer, MDX, DeEcho, etc.) — not tracked in git
Lua/                           all active ReaScripts, grouped by purpose (see sections below)
Shell_Scripts/                 unpack.sh, unzip_nam_ir_library.zsh
MIDI/Basement_Drum_Grooves_20/ 20 drum groove MIDI files + README
Docs/                          tone bibles, gear inventory, guides
Track_Templates/                .RTrackTemplate files
Retired_Superseded/             older/duplicate scripts kept for reference, not wired into the workflow

Top-level pipeline files

These four are deliberately left at the repo root instead of folded into Lua/ or Shell_Scripts/ — they resolve each other's paths by relative location (Split-Audio.lua finds auto_uvr.py next to itself, auto_uvr.py finds UVR_Models/ the same way, run_uvr_pipeline.command hardcodes the path to auto_uvr.py). Moving one means updating the others.

• Split-Audio.lua — Ctrl+Shift+U in REAPER. Triggers the UVR extraction pipeline from inside REAPER: writes a temp .command file next to auto_uvr.py and opens it in Terminal so you get a visible progress log instead of a silent background run.
• auto_uvr.py — Called automatically, not run directly. The separation engine itself. GUI picker for Vocals-only / Instrumental+Drums / Full pipeline. Chains BS-Roformer (vocals) → MDX-Net (instrumental) → Demucs (6-stem split) → MDX23C (drum-piece separation) → DeEcho/DeReverb cleanup, writing everything to Stems/UVR/.
• run_uvr_pipeline.command — Double-click in Finder. Terminal launcher for auto_uvr.py. Drop a WAV onto it, or run it with no argument and it opens a native file picker rooted at ~/Documents/Music Projects/.
• fadr_cloud.py — Called automatically by Fadr_MIDI_Extract_v6_LastUsed.lua, not run directly. Backend for Fadr MIDI extraction: uploads to S3, polls the task, downloads the resulting MIDI.

Lua/Pipeline_UVR_Fadr

Stem separation follow-up and Fadr MIDI/chord import.

• Fadr_MIDI_Extract_v6_LastUsed.lua — Ctrl+Shift+F. Glues the selection, uploads it to Fadr's cloud API, polls for MIDI extraction, and loads the result into a VSTi you pick from a GUI menu (Kontakt, Vital, Surge XT, NAM, etc).
• Fadr_Chord_Mapper.lua — Alt+C. Finds a Fadr chord-detection CSV near the selected audio item, parses ~25 chord qualities, and writes exact time-anchored MIDI chords + markers to a dedicated muted "Chords/Textures" track (auto-created if missing).
• Ferrett_FadrPlus_Organizer.lua — Action List. Creates 5 empty tracks (fadr_drums/bass/keys/vocals/other) for manually dragging in a Fadr+ stem export.
• Ferrett_GoogleFlow_Importer.lua — Action List. Imports a Google Flow AI-generated song: a "FLOW ORIGINAL" reference track plus a 4-track triage folder (Flow Stems / Rerecord / MIDI Replace / Keep Audio) to sort the AI output into.

Lua/Project_Setup

Session and arrangement scaffolding.

• Autoproject_setup_master.lua — Ctrl+Shift+A. The big one: recursively scans the song folder for every UVR/Fadr stem, builds the full routed session (vox/synth/bass/guitar/drum buses + FX chains per stem), mutes the original master, and archives unmatched Fadr stems.
• BeatBlocks.lua — Action List. Takes a time-selected 4/8-bar loop and duplicates it into a full arrangement (Intro → Verse → Hook → Verse → Hook → Outro) with color-coded region markers, muting drum tracks in the intro/outro for a beat-drop. Edit the SONG table at the top of the script to change the structure.
• Ferrett_Arrangement_Template.lua — Action List. Sets project tempo to 86 BPM and drops markers for a fixed basement hip-hop structure. Markers only, no audio — lays out an empty map to track against, as opposed to BeatBlocks which duplicates real content.

Lua/Bus_Builders

• Ferrett_Bass_Bus_Builder.lua — Action List. 5-string bass bus: tuner → SVT-VR → Nova → 1176 → IVGI2 → HPF28.
• Ferrett_Drum_Bus_Builder.lua — Action List. Drum bus: Transient Shaper → CHOW → Kotelnikov → S73.
• Ferrett_Synth_Stack_Builder.lua — Action List. Builds a 5-layer synth chorus stack (Sub/Body/Air/Movement/Glue) inside a folder track with bus glue.

Lua/Vocal_Chains

• VocalBooth.lua — Action List. Run this first. One-key full vocal session builder, not just a tone chain: creates a "VOCALS" folder with an armed/monitoring Lead Vox (EQ → Comp → DeEsser → Saturation), panned Double L/R tracks, an Adlib track, and Verb/Delay send buses, tailored to a UA Volt 176 input chain. Apply one of the chains below onto the Lead Vox track it creates.
• Flow_Vocal_Pro_v2.lua — Ctrl+Shift+V. Cheap-mic/bad-room fix chain: ReaEQ (bad-room preset) → TDR Nova → ReaComp → ReaXcomp de-ess → Saturation Knob → Graillon 2 → OTT.
• Ferrett_Vocal_Chain_Chorus.lua / Ferrett_Vocal_Chain_Rap.lua — Action List. Two produced-room chains (good mic assumed): melodic chorus-wide vs. percussive rap-tight, both built from owned UAD/kHs gear.
• Ferrett_Vocal_Blues_Grit.lua — Action List. Sung blues-chorus chain: 610-A drive, 1176, Saturation Knob, Sound City room, Supermassive hall, Nova de-ess.
• Ferrett_Owned_Comp_Rap.lua / Ferrett_Owned_EQ_RapVox.lua — Action List. Split comp-only / EQ-only halves of a rap vocal chain, built strictly from owned gear (1176, kHs Dynamics, Kotelnikov/TDR Nova, kHs 3-Band, 610-B).

Lua/Guitar_Bass_Tone

• Load_Mega_Tone_Menu.lua — Ctrl+T. The main tone loader: reads ~/Music/NAM_Rig/presets.txt, builds a nested right-click menu, and loads Gateway + a standard mix chain + the preset's specific FX.
• Ferrett_Gateway_Bass_5String_Pocket.lua / Ferrett_Owned_Bass_5String_Pocket.lua — Action List. Same 5-string bass tone, two plugin paths: Gateway (NAM captures + IRs in one plugin) for the real captured amp tone, or Owned (Ampeg SVT-VR Classic + ReaVerb IR) for zero-latency tracking.
• Ferrett_Gateway_Guitar_Blues_Edge.lua / Ferrett_Owned_Guitar_Blues_Edge.lua, Ferrett_Gateway_Guitar_Distorted_Rhythm_Wall.lua / Ferrett_Owned_Guitar_Distorted_Wall.lua, Ferrett_Gateway_Guitar_PalmMute_Harmony.lua — Action List. Same Gateway-vs-Owned pairing for guitar tones (blues edge, distorted rhythm wall with quad tracking, palm-mute harmony under bass).
• Ferrett_Bass_Blues_Slide.lua — Action List. B15N + IVGI2 + LA-2A
  • Supermassive, for slide/ghost-pop bass technique.
• Ferrett_Keys_Rhodes_Basement.lua — Action List. VB-Dandy + Pure Plate + Kotelnikov + CHOW, warbly basement Rhodes.
• Ferrett_Drum_Vinyl_Crunch.lua — Action List. ReaSamplOmatic5000 kit + Cassette + IVGI2 + Transient Shaper + Supermassive.
• Ferrett_ToneMatrix_Expanded_150.lua — Action List. 150 procedurally-generated amp/cab/mic pairings (bass + guitar), loaded via plugin + manual ReaVerb IR.
• Ferrett_Gateway_ToneMatrix_150_Owned.lua — Action List. Same idea, but with real owned NAM captures and IR names pulled from your gear inventory, loaded via Gateway.

Lua/Trash_and_Echo_FX

• DustMachine.lua — Action List. Two auto-detected modes: track mode applies a lo-fi dust chain (pitch wobble, bitcrush, EQ rolloff, saturation) to the selected track; item mode writes an actual pitch-drop envelope for a tape-stop transition on the selected item's last ~0.8s.
• Ferrett_Effects_Throw_Builder.lua — Action List. Builds a dub/tape-stop FX-throw bus (Supermassive, Galaxy Tape Echo, ReaDelay, ReaPitch) with manual automation instructions.
• Ferrett_Owned_TapeEcho_8Presets.lua — Action List. 8-preset echo menu (Slap / Dub Throw / Old School Plate / LoFi Warble / Stereo Ping Pong / Megaphone Slap / Blues Call / Basement Chamber), owned gear only.
• Ferrett_Owned_Trash_Morph_Container.lua — Action List. One-knob "mild to megaphone" morph using an FX Container with owned plugins, with a fallback to a flat chain if containers aren't supported.
• Ferrett_Owned_TrashVocal_6Stages_Gateway.lua — Action List. One popup menu covering all 6 trash-vocal stages (Mild Tape → Warm Cassette → Crunch → LoFi Radio → Telephone AM → Beastie Megaphone).

Lua/MIDI_Cleanup

Fixes for AI-generated MIDI. Run individually, or all at once via the macro.

• Ferrett_GhostNote_Purge.lua — deletes AI-hallucinated notes shorter than a 1/32nd note.
• Ferrett_Legato_Fix.lua — forces a small gap between overlapping notes so mono synths retrigger correctly.
• Ferrett_CC_Cleanup.lua — deletes hallucinated pitch-bend and mod-wheel (CC1) data.
• Ferrett_Bass_Range_Fix.lua — moves notes below E1 up an octave, protecting the keyswitch zone.
• Ferrett_Velocity_Stalk_Fix.lua — detects flat AI velocity (>80% identical) and rebuilds musical dynamics.
• Ferrett_Drum_Humanize_Pocket.lua — humanizes timing/velocity, keeps kick/snare tight, ghosts loose, pushes drums 4 ticks late for pocket.
• Ferrett_Basement_Clean_Macro.lua — Action List. One-click chain that runs all 6 scripts above in sequence.

Lua/Sampling_and_MIDI_Generation

• HipHop_ChopSuite.lua — Action List. Fully automated sample chopper: splits the selected item at transients, moves each chop to its own colored/named track (PAD 01, PAD 02...), applies pitch-down + a starting lo-fi EQ per chop.
• Ferrett_Sample_Chop_Template.lua — Action List. Different from ChopSuite: builds 16 empty MIDI trigger pads (C1–D#2) for a ReaSamplOmatic5000-based "play live" chop kit, rather than auto-slicing an existing recording.
• Ferrett_MIDI_From_Audio_Melody.lua — Action List. Adds ReaTune to a take for humming/synth-line-to-MIDI conversion, with instructions to enable pitch-to-MIDI and re-record.
• 1_euclidean_rhythm_gui.lua — Action List, requires ReaImGui. Live Euclidean rhythm sequencer with a visual step grid and a PLAY button that auditions the pattern through REAPER's Virtual MIDI Keyboard before you write it to a MIDI item. Select a track with an instrument (e.g. ReaSynth) first to hear it.
• 2_markov_melody_gui.lua — Action List, requires ReaImGui. Learns note transitions from a source item, generates a new melody, then plays it back (looping) through the Virtual MIDI Keyboard so you can audition before it lands in your project.
• 3_glitch_slicer_gui.lua — Action List, requires ReaImGui. Interactive glitch/IDM audio slicer — dial slice count + chaos, toggle which tricks are allowed (repeat/reverse/pitch/half-time), GLITCH, then audition the edited item via the transport (it loops over the item's time selection; STOP halts playback).
• 4_chord_composer_gui.lua — Action List, requires ReaImGui. Functional-harmony chord progression generator with voice leading — pick key/mode, roll a progression, audition it as block chords through the Virtual MIDI Keyboard, then write it to a MIDI item.
• 5_human_groove_gui.lua — Action List, requires ReaImGui. Humanizer with live sliders (swing/jitter/drift/velocity feel). LOAD snapshots the original note positions so every APPLY re-feels from the clean original instead of compounding; PLAY auditions the current settings before you commit with APPLY.

Lua/Stem_Workflow_QA

• Ferrett_Stem_Triage_Tagger.lua — quick popup to tag a track KEEP/RERECORD/MIDI/TRASH; auto-mutes anything tagged TRASH.
• Ferrett_Synth_Keep_vs_Replace.lua — popup for 3 synth-fix scenarios: mono pad widening, out-of-key lead to MIDI, thin chorus to a full stack.
• Ferrett_Mixed_Bag_Finalizer.lua — pre-mix QA scan: flags [TRASH]-tagged tracks that aren't muted, shows a headphone-check reminder.
• Ferrett_Drum_Keep_Augment.lua — adds a parallel crush send (1176 + Decapitator) without replacing the original drums.
• Ferrett_Drum_Full_MIDI_Replace.lua — track setup for fully replacing messy AI drums with SSD5 MIDI.
• Ferrett_Bass_Rerecord_Helper.lua — creates a DI guide track with a tuner for re-recording AI bass with a real 5-string.

All six run from the Action List with a track/item selected.

Lua/Rendering_QA

• Flow_OneClick_Render_v2.lua — Ctrl+Alt+R. Solos and renders VOX/INST/MIX buses to dated filenames, reporting exactly which buses rendered and which were skipped.
• Render_Amps_To_Audio.lua — Action List. Renders every "AMP - *" track to a stem and disables the live amp-sim FX on the original (freeze workflow for CPU relief / re-amp safety).

Lua/Reference_Tools

• lyrics.lua — Action List. Floating lyrics-prompter window driven by project markers, with a dimmed "next line" preview synced to the playhead.
• Ferrett_Cookbook_Recipe_Finder.lua — Action List. Asks what elements you have on hand (bass, guitar, vox type, drums, etc.) and suggests genre-appropriate arrangement combos.

Shell_Scripts

Run from Terminal, not REAPER's Action List.

• unpack.sh — batch-unzips NAM amp packs sitting in the current folder into ~/Music/NAM_Rig/Amps/<name>/, one folder per zip.
• unzip_nam_ir_library.zsh — watches ~/Downloads for NAM zips and auto-sorts them into NAM_Rig/Amps vs /IRs by filename, stripping __MACOSX junk.

Track_Templates

Load via REAPER's Track → Track Templates → Insert Track from Template.

• NAM_Re-Amp.RTrackTemplate — re-amping track template.
• BASS_5STR_Basement.RTrackTemplate — 5-string bass basement tone chain template.

MIDI/Basement_Drum_Grooves_20

20 individual 4-bar drum groove MIDI files, 76–94 BPM, 52–64% swing, with pocket nudges baked in. Mapped for SSD5 (kick 36, snare 38, ghost notes 12–28 velocity, hats 42/46). Drag from REAPER's Media Explorer with tempo match on — see the folder's own README.txt for the full mapping notes.

Docs

• Tone_Bibles_HTML/ — 7 self-contained reference documents: basement production bible, Cubase3-to-REAPER migration guide, mixed-bag workflow, owned-gear inventory bible, tone cookbook, trash-vocal/tape-echo lab, and an EQ/comp/signal-chain bible. Open any of them directly in a browser.
• Gear_Inventory/OWNED_INVENTORY.txt — plaintext scan of owned amps/EQ/dynamics/FX/instruments/NAM captures/IRs, the source of truth the "Owned" tone scripts are built against.
• Guides/Gateway_NAM_IR_Guide.txt — workflow notes on keeping IRs loaded inside Gateway vs. a separate ReaVerb, plus recommended NAM+IR pairings per tone.
• Guides/Bad_Room_Fix_Preset.txt — the exact ReaEQ/Nova/Saturation/ Graillon/OTT settings for cheap-mic/untreated-room vocals (matches Flow_Vocal_Pro_v2.lua).

Retired / Superseded

Kept in Retired_Superseded/ for reference rather than deleted — each one was replaced by something in the active tree that does the same job better:

Retired	Superseded by
Ferrett_Teleprompter.lua	Lua/Reference_Tools/lyrics.lua
Ferrett_Fadr_CSV_To_Markers.lua	Lua/Pipeline_UVR_Fadr/Fadr_Chord_Mapper.lua
Ferrett_UVR5_Bridge.lua	Split-Audio.lua + auto_uvr.py
Ferrett_Owned_Trash_Morph_Container_v1_draft.lua	Lua/Trash_and_Echo_FX/Ferrett_Owned_Trash_Morph_Container.lua
Ferrett_Owned_TapeEcho_Slap110.lua, Ferrett_Owned_TapeEcho_DubThrow350.lua	Lua/Trash_and_Echo_FX/Ferrett_Owned_TapeEcho_8Presets.lua (presets #1–2)
Ferrett_Owned_Trash_Stage1_Mild.lua … Stage6_Megaphone.lua	Lua/Trash_and_Echo_FX/Ferrett_Owned_TrashVocal_6Stages_Gateway.lua
Ferrett_ToneMatrix_Basement.lua	Ferrett_ToneMatrix_Expanded_150.lua / Ferrett_Gateway_ToneMatrix_150_Owned.lua
Ferrett_Guitar_Blues_Chain.lua, Ferrett_Guitar_Distorted_Rhythm.lua, Ferrett_Guitar_PalmMute_Harmony.lua	the Owned/Gateway variants in Lua/Guitar_Bass_Tone/
Ferrett_Transient_To_MIDI.lua	Lua/Sampling_and_MIDI_Generation/HipHop_ChopSuite.lua
fadr_cloud_loose_copy_from_Documents_root.py	fadr_cloud.py

See 00_READ_ME_Catalog.txt for the full session-by-session notes on why each of these was retired.