operation manual · iOS 0.2.18

logic behind epicMIDI

This is the operator’s book as of 0.2.18.

1. What it is

epicMIDI is an iOS MIDI studio: a launch-pad sequencer, a MIDI clip bank, a piano roll, dual performance surfaces, a circle-of-fifths instrument, and (when the engine is On) a mixer that hosts third-party AUv3 generators and effects. It can make sound with a small onboard sine engine, or run silent as a MIDI brain for other apps and hardware.

• iPhone and iPad. Landscape is the native shape but it is designed to scale to all screens; the chrome collapses as width shrinks.
• Opens on SEQ.
• Pages: SEQ · BANK · ROLL · PERF · HARM · MIX (MIX only when Audio Engine is On).
• Timebase is 1920 PPQN internally. Pattern steps are 16th notes.
• Every Note On is paired. Panic flushes sounding notes and sustain.

2. Chrome

Two strips sit above every page:

1. Top bar — logo tile (tap = about), record, measure, tempo/clock, SEQ/BANK/ROLL/PERF/HARM/MIX, volume, settings, panic triangle. MIDI monitor appears on the right when there is width.
2. Pattern bar — play/stop (pinned left), SEQ/PAT, pattern tiles. On SEQ: screwdriver + trash pin right. On BANK: trash pins right. Pattern tiles scroll under the pin cluster.

3. Transport

Play lives on the pattern bar, left edge, and stays pinned while tiles scroll.

The clock cluster’s repeat icon is the song loop, not the clip loop. PAT already loops the selected pattern via STEPS. Next to the icon: − N BARS + (default 4, range 1–64). Bar length follows the time signature — 4 bars of 3/4 is four bars of 3/4, not a leftover 4/4 span.

Time signature lives in that same popdown (2/4 … 12/8). It drives bar lines on the roll, metronome accents, and the song-loop length.

Metronome is a short wood-block click, independent of master volume; click level is in Settings. First downbeat includes the click when metronome is on.

Follow-playhead on the roll (|<|>) chases the playhead inside the pattern length — a 1-bar clip in a 4-bar song stays on that bar, it does not walk into empty space. In SEQ, if that clip is not on in the grid, the playhead is ghosted.

4. Pattern bar

• Tap a tile to select it (white border). Double-tap opens ROLL for that pattern.
• Hold still ~0.2s, then drag to reorder. Linear position is the pattern number; grid tiles that point at it update. A flick without the hold scrolls the bar.
• The dashed + after the last clip appends a new empty pattern and opens the roll. A new project starts with one empty pattern, not eight.
• Selected pattern in the bar does not play from transport by itself — grid tiles (SEQ) or PAT mode do.
• There is no BANK button here. BANK is a page in the top cluster (and a jump from the SEQ edit rail).

Screwdriver + trash: SEQ page. Trash only: BANK page. Both cans accept any dragged tile.

5. Lift / drop

6. SEQ

Performance (edit off)

• Tap an empty slot’s + to drop the selected bank/pattern onto it. New tiles come on.
• Loop tile: tap toggles on/off. Playing tiles fill grey left-to-right with progress.
• 1-shot: tap plays through once.
• Hold: sounds only while the finger is down.
• Last-touched tile is the implicit selection for delete / opening edit. No yellow border outside edit.
• Hold-to-delete on the trash fills that pad red at the same rate as the can.

Edit (screwdriver)

Opens the right rail (stops under the SEQ menu bar). Tapping a tile selects it and shows its settings — it does not trigger. Double-tap a tile opens ROLL. A MIDI-green wireframe pulses around the grid while edit is on. The screwdriver pulses a matching green border. Hold a selected tile, then tap another slot to duplicate there. Child copies letter A–Z after the parent number; past 26 the label is FU.

Rail (selected tile):

Toggled-off tiles keep a ghost of their notes. Empty unused slots stay dark.

7. BANK

BANK is its own page. It is not an overlay on SEQ, so drops cannot fall through onto the grid. It is the MIDI clip library — independent of the pattern bar and of the grid.

• Folders at the root. Tap a folder to enter; BACK returns. Folders save and load with the bank file.
• Tap a clip to select (white / focused). Double-tap appends it to the pattern bar and scrolls to it.
• Hold still ~0.2s and drag a clip onto the pattern bar (inserts / parts existing tiles), onto a folder, or onto a trash can.
• Play in the rail auditions the selection without the main transport.
• + Dir makes a folder. Del Dir asks ARE YOU SURE? Clips in that folder stay, moved to root.
• MIDI Import / Export on the rail. Type 1 SMF splits to several clips. Export bakes clip transpose.
• BANK FILE Load / Save is the whole library (clips + folders). Settings NEW BANK asks ARE YOU SURE and wipes clips only — not the pattern bar, not the grid.
• ADD SEQ TO BANK / + Mid writes the current pattern-bar clip into the library. It lives only in this rail, under BANK FILE.

There is no MOVE TO list. Drag a clip onto a folder instead.

8. ROLL

Two bars. Top: ROLL | SEQ [#] | N STEPS − + | draw box drag | snap | follow. Second (SEL): Q HUM | TRANSPOSE −1 +1 with undo / redo / trash pinned right. Dest and channel are not on these bars — they live on the keyboard strip under the roll.

• SEQ # is the first control after ROLL |. It picks which pattern the roll is editing.
• N STEPS is the clip length in sixteenths (dropdown of common lengths, − / + beside). Range 1–256. Does not change note length — that’s snap. Recording into the selected pattern-bar clip grows STEPS as needed. Song loop stays at N bars.
• Batteryblock toggles snap, then the division menu (1/1 … 1/16). Snap only affects draw / quantize / stretch — not pattern length. Faint verticals follow the snap division.
• Q / HUM / TRANSPOSE on the SEL bar apply to the selection (or all notes for HUM if nothing is selected). Undo / redo / trash stay pinned on the right of that second bar. Trash is the receptacle icon only.
• Keyboard dest + CH under the roll are the active pattern’s destination and channel. Pitch and mod wheels send on that dest/CH. Ø = off.
• Automation lane (cellularbars): VEL / PROB / CC1 / PB. Velocity and probability are per-note bars (drag across; stacked notes at the same start all move together). PROB is 0–100% per note, default 100; each loop cycle rolls independently. CC1 and PB paint a lane of dots.
• Snap-to-view (eye) fills the left keyboard gutter on the measure bar — tap it to fit active steps horizontally and the used octave vertically. Not a toggle.
• Measure bar is pinned top; automation lane pinned bottom. Content does not hide behind them at the scroll extremes.
• Keyboard under the roll is pulled by the stipple bar. At max rail compression the right controls collapse to a menu, then off-screen; keys and wheels keep height to the stipple.

9. PERF

Two independent surfaces (UPPER / LOWER), defaulting to pads. Each has its own dest, channel, scale/root, left rail, and right rail.

• Left rails match the right rail width so portrait does not clip the right controls.
• Landscape + low height: hide the upper VV XY pad; vel/vol fill. Knobs and sliders scale to the pane so LOWER is not eaten. XY dest/CC move into the UPPER/LOWER popouts.
• Width under 650pt: two-octave keyboard.
• Velocity fader on VV is the strike cap for that surface’s keys.

10. HARM

Menu bar is a single full-width scrollable row: HARMONY | C1 chord dest/ch | 1/2 circles | C2 chord dest/ch | keys dest/ch. C1 cluster sits over circle 1, C2 over circle 2, circles selector in the middle. Keyboard starts swiped down; the keys glyph shows/hides dest/CH for that manual.

• Hold a chord, then another — both sound. Release order does not stick notes.
• Chord readout is per circle and returns to a dash on release. C1 is C1, C2 is C2 — sequencer and the other circle do not write the name.
• Layouts live in the side rail as 1/5 1/4 1/12 (fifths / fourths / chromatic). Scale + root sit above Rings. Each ring has an octave ±3.
• C1 and C2 do not share held notes or lights. A chord on circle 1 does not light circle 2, and does not steal its voices.
• The HARM keyboard under the circles is a third surface. Off by default. It does not share hold-state with either circle.
• C1/C2 rails are scrollable and stop under the harmony menu bar.

11. MIX

MIX only exists when Settings → Audio Engine is On, and only in the standalone app. Off and Dummy hide the page. Hosted inside AUM, On is refused and MIX does not exist.

• Catalog of generators and effects (third-party App Store AUv3s, plus Apple units if that toggle is on). Rescan if a newly installed plug-in is missing.
• Tap icon or UI to expand the plug-in under that mixer row — no floating window. The pane width-fits the mixer; height is capped, with a stipple rail along the bottom. Drag the stipple up to shrink, down to grow. A wider right margin is there to grab the mixer scroll, not a scrollbar.
• Only one UI expanded at a time. Expanding another collapses the last.
• MIX menu bar: dest picker (loaded AUs only — no DEFAULT / CoreMIDI) is linked to whichever UI is expanded. Change the dest → that AU expands. Expand an AU → dest follows. Channel sits next to dest. Mix keys, pitch, and mod go only to that plug-in, never to the virtual MIDI out or other apps.
• Keyboard button pops an adjustable-height manual under MIX (stipple like ROLL, no velocity lane). Track picker to its left is the same dest link.
• FX rows: delete X in front, wetness, up/down at the back. Second instance of the same unit is named NAME 2.
• Loaded generators appear in MIDI destination menus (SEQ rail, ROLL dest, PERF dest, HARM dest). New grid tiles inherit dest from their parent, then stay independent.

12. Manuals / keyboard

• Visible range: three octaves, two under 650pt width. adjustable with Oct Range setting on the manuals
• Velocity from vertical position (top of the key = harder).
• Right rail: GLISS, LATCH, MONO/POLY, PEDAL (hold). Octave range and root live on the keys menubar with dest/CH, PM/VV (where that surface has it), and scale. Left rail on PERF is PM or VV (see §9). ROLL wheels follow the keyboard dest/CH. MIX wheels follow the MIX dest/CH.
• Gliss: slide across keys, polyphonic if POLY is on.
• Latch: tap to hold, tap again to release that key. Turning LATCH off sends note-offs for anything you are not still holding — unless PEDAL is down, in which case the pedal keeps them until you lift it.
• PEDAL is hold-only. Down keeps sounding notes (and sends CC64). Up sends note-offs for notes that are not still pressed and not still latched. It is not a toggle.
• Mono: last-note priority. Hold C, tap E, C goes quiet; release E and C resumes. Same surface only.
• Note on and note off use the surface’s channel. Changing CH mid-hold is a new voice — lift, then play.
• Keyboard rails can collapse at any width. Stipple bars drag to resize. Hit area is larger than the dots. Intersecting stipples blend; no hard joint line.

13. Settings

On a narrow or short screen the MIDI monitor and BPM cluster migrate into this rail so the top bar stays readable.

14. Files

Import MIDI from Files / share sheet. New clips append and the bank list scrolls to them. Export bakes the clip transpose.

15. MIDI I/O & clock

• Virtual source name: epicMIDI. Virtual destination: Epic MIDI In. Our own published packets are not re-ingested — no self-echo on the input.
• In CH: Ø ignores channel voice (clock still works). Omni accepts all. A number filters to that channel.
• Dest + CH are per surface. The MIDI monitor prints that surface’s channel, not a master. Thru forwards incoming MIDI out the virtual source; it does not remap to a global Out CH (there isn’t one).
• You can change ports while playing.
• Background audio stays on so MIDI keeps flowing when the app is minimized.
• CC1 = mod, CC64 = sustain, pitch bend, CC120/123 = panic. Note On velocity 0 = Note Off.
• Internal PPQN 1920. Clock 24 PPQ.

The green monitor is a 4-line trace of recent channel voice / CC / bend. It is not a log you can export.

16. AUv3

Two roles, never at the same time:

• Hosted mode does not open CoreMIDI virtual ports (that killed AUM’s helper). Sequencer, keys, and harm emit MIDI through the AU event block into AUM’s graph.
• Onboard synth is 32-voice sine with a short ADSR, idle-silent (no per-sample loop when no voices). Standalone Dummy uses it. Hosted AUM does not.

17. Gesture sheet