Troubleshooting

No audio

1. Check iPhone output volume and the current route (speaker, headphones, interface, AirPlay).
2. Press PLAY from Song and confirm the play marker moves.
3. Clear solo/mute states with ALT+NAV.
4. Check channel and master faders plus the meters.
5. For SAMPLE instruments, verify the project sample exists and is assigned.
6. For AU instruments, verify slot load, bypass, level, MIDI channel, and preset.
7. Stop playback, switch projects, then return if the audio graph appears stale.

An audio session that is interrupted — a call, another app taking the route, or hardware being unplugged — recovers on its own. If the play marker has stopped, press PLAY again rather than relaunching, and report it if audio does not return.

First-play stutter or lag

GlassTracker prepares restored AU instruments and effects during project load. On a cold launch, a short Loading project audio… panel is expected for AU-heavy projects. Playback should begin only after it clears.

• If you press PLAY before loading finishes, wait for the panel rather than tapping repeatedly.
• Close expensive AU editor UIs and test again.
• Reduce the project to one AU and no inserts to identify the plug-in causing cold-start pressure.
• Relaunch and note whether the problem occurs only on the first process launch.
• Report the plug-in names, device model, iOS version, audio route, and whether the second launch is clean.

Chopping, resets, or recurring underruns

• If you lowered Device → Audio Buffer Size, return to 1024 frames and retest. Then try 512 once the project is stable.
• Stop transport and remove/bypass one Audio Unit at a time.
• Lower AU polyphony, unison, oversampling, and internal effect quality.
• Adding and removing plug-ins during playback is supported, but it still costs CPU at the moment of the change. Retest with the transport stopped to separate a rewire cost from a steady-state underrun.
• Disconnect Bluetooth audio and retest on speaker/wired output.
• Allow the device to cool; sustained synths and real-time effects can thermal-throttle older phones.
• Restart the affected AU app and GlassTracker if its extension process became unhealthy.

Project is slow to load

Large sample pools, spilled AU state, multiple cold extensions, and plug-ins that restore slowly all add time. GlassTracker deliberately waits for conservative state checks so the first playback uses the correct patch.

• Remove genuinely unused samples and Audio Units after backing up.
• Save the simplified project under a new name and compare load time.
• Do not interrupt a project switch by repeatedly pressing PLAY or opening another project.
• A few seconds can be an accepted Alpha limitation; indefinite progress or a repeated fallback is a bug.

An incomplete untitled scratch project is rebuilt automatically and should not leave the app on an Invalid Project screen. If a named project is reported as invalid, GlassTracker preserves its folder for recovery; acknowledge the warning, open another project, and back up the affected folder before changing it in Files.

Insert or clone will not create a new chain or phrase

Chain and phrase numbers are a fixed project pool. Numbers no longer referenced by the song return to it, so a refusal now means the pool really is exhausted rather than leaked.

• Reuse an existing phrase with a chain transpose value instead of cloning another copy.
• Clear chains and phrases you abandoned; their numbers become available again.
• Move a finished section into its own project if the arrangement has outgrown one pool.

AU is missing, empty, or crashed

Add AU list is empty

1. Confirm the app is an AUv3 instrument/effect, not only a standalone app.
2. Launch the AU app once and complete any first-run setup.
3. Return to GlassTracker and reopen Add Instrument/Effect; discovery retries transiently empty registries.
4. Restart the iPhone if iOS has not registered a newly installed extension.

Saved slot says missing

To preserve the saved patch, do not remove the slot. Reinstall the same AU component and vendor, reopen the project, and let GlassTracker restore the preserved state.

Plug-in crashed

GlassTracker attempts up to a bounded number of automatic reinstatements with cached state. If it degrades to missing, save a copy, restart the AU’s standalone app, then relaunch GlassTracker.

MIDI or AU route is silent

1. Reduce the test to one note and one MIDI instrument. Confirm the Phrase row references that instrument.
2. Check its DEST: use AU RACK or ALL for a rack synth, and MIDI OUT or ALL for hardware/another app.
3. For an AU, match the instrument Channel to the slot's LISTENS ON. Its DELIVERS AS normally stays at channel 1 unless the plug-in is multitimbral.
4. For incoming hardware, enable its source under Device → MIDI Ports, turn on Receive MIDI, and check that incoming channel's route under MIDI Input.
5. Disable Program Change temporarily so it cannot select an unintended patch. Remove VEL commands and use Length 00 for a full-velocity sustained test note.
6. If the AU accepts MIDI but stays silent while its standalone app or AUM works, enable that rack slot's Compatibility switch. Switching host preserves its state and routing.
7. For Bluetooth, reconnect in Device → BT MIDI.

An AU's internal sequencer is not synchronized

1. Set the project tempo before loading the plug-in, then start from a stopped transport for the first comparison.
2. Use a sustained tracker trigger (Length 00) if the plug-in's sequencer runs only while a note is held. A short note can make the pattern appear to reset or drift.
3. Leave MIDI Nudge at 0 ms. Nudge corrects a fixed onset error, not tempo or phase.
4. Confirm the plug-in receives GlassTracker's host tempo/beat/transport context; most AUs should synchronize from that alone.
5. If that specific AU requires MIDI realtime messages, reveal Advanced Options and enable MIDI Clock for only its slot. This supplies Start/Stop and 24-PPQN clock at its render boundary.
6. Do not enable per-slot clock speculatively: a plug-in that follows host context and clock at once may run fast, reset, or change phase.

A brief rapid step display while a plug-in first acquires host state can be plug-in behavior. It should settle to the project grid; repeatable tempo error or a different phase on every start is not expected.

System keyboard will not dismiss

On Add AU and CC parameter screens, press DOWN while the search field is focused. Focus returns to the current list row and the keyboard dismisses without skipping it. Tapping the list, a row, Cancel, or Done also dismisses the keyboard.

Files import or project backup problem

• Only supported WAV files appear in the import workflow.
• Wait for iCloud/provider downloads to complete before retrying.
• Imports larger than 256 MiB are rejected.
• Copy the whole project folder, including gtsav.json and samples.
• Do not uninstall GlassTracker before verifying the backup exists outside On My iPhone → GlassTracker.

Recording does not start

1. Stop song playback.
2. Check microphone permission in Settings.
3. Open INPUT and select an available route.
4. Open CHANNELS and verify the connected source is on the selected mono input or stereo pair.
5. Disconnect/reconnect the interface if iOS no longer lists it.
6. Check free device storage and that no previous take is still saving.

Render is slow, silent, or different

• AU/FX mixdowns intentionally run in real time; engine-only mixdowns run offline.
• Stems are dry and do not include iOS insert/send processing.
• Check the starting Song row, mute/solo state, and whether the song has a reachable end.
• Keep the audio route stable during a real-time bounce.
• Verify the resulting WAV rather than judging transient sounds heard while offline rendering.

Timing or latency sounds wrong

• For delay between an external MIDI key press and sound, stop playback and recording, then try Device → Audio Buffer Size at 512 frames. Smaller values reduce live latency but increase CPU pressure; 1024 is the stability default.
• Bypass the suspected insert and compare.
• Check the Mixer PDC value and the plug-in’s reported latency badge.
• The engine and AU graph share one sample rate granted at boot, normally 48 kHz on a modern iOS device. Imported and bundled WAV files may remain 44.1 kHz without changing that render clock.
• Test speaker/wired output instead of Bluetooth audio.
• External MIDI/device latency is not the same as internal AU scheduling.
• At 0 ms, AU Rack MIDI Nudge means PDC only; it does not disable automatic compensation.
• Recording round-trip latency is not yet automatically compensated in the Alpha.

Writing a useful Alpha report

Include:

• GlassTracker version and build.
• iPhone model and exact iOS version.
• Audio route and buffer-sensitive hardware.
• AU app/name/version and patch, if relevant.
• MIDI devices and wired/Bluetooth transport.
• Whether it happens on fresh launch, second launch, or both.
• Minimal exact steps, expected result, actual result, and frequency.
• A copied project folder when the issue is project-specific and safe to share.

Device → Discord opens the community server, which is the place to send reports and ask about behavior you are unsure of.