Where Local-First Design Meets the Real Machine
Meetily can keep capture, transcription, and selected summary work on local infrastructure, but that capability depends on an operating system, physical devices, model files, package resources, and user choices. This chapter diagnoses the failures and trust boundaries that appear when the design meets a real machine. The reader will be able to separate a permission problem from an audio-routing problem, understand what microphone recovery does and does not restore, and check whether telemetry, updates, and bundled runtimes fit a sensitive-meeting policy.
The important shift is from asking whether Meetily is “local” to asking which transition failed. A local recognizer cannot help if the operating system delivers silence. A saved transcript does not prove that the audio file was finalized. An opt-in analytics control reduces one data path without changing the update channel. Each symptom has to be connected to the state and boundary that produced it.
When capture fails, locate the failed transition
The first diagnostic distinction is whether recording was ever allowed to start. Meetily validates the local transcription model before it creates the active recording resources. If the model is missing, corrupt, still downloading, or unable to initialize, the start path reports a startup error. That is different from a session that starts successfully but later produces no text. In the first case, the failed transition is model readiness; in the second, the cause lies farther along the audio, segmentation, or recognition path.
A similar distinction applies to permissions. On macOS, Meetily checks microphone access by creating a short test stream and waiting for an actual callback. A stream object can exist without usable samples when permission has been denied, so a successful API call is not enough evidence. Direct Core Audio capture has a related limitation: a tap may be created while the resulting audio is silence. If a recording begins but both the recording and transcript lack expected sound, the operator should investigate permission and device delivery before changing summary settings or blaming the language model.
System audio creates a second branch in the diagnosis. The application may have a working microphone while the computer’s playback is not exposed through the selected loopback or monitor source. Meetily’s platform code uses different mechanisms for different systems: Windows has a WASAPI output-device path intended for loopback, Linux looks for PulseAudio monitor sources, and macOS can use a direct Core Audio path or another configured backend. A device name in a picker is not proof that the operating system will deliver the desired playback stream.
The repository contains an important support caveat. Active stream and device modules include platform-specific paths for selecting system audio, but a separate convenience capture function is explicitly unimplemented outside macOS. Documentation describes broader Windows and Linux support than that function provides. The safest diagnosis is therefore conditional: determine which active stream path the current build uses on the target platform, then test the actual callback and samples. Do not infer cross-platform equivalence from the presence of a shared command name.
Meetily’s startup sequence helps narrow the fault. It loads preferences, resolves a requested microphone or falls back to the system default, resolves system audio separately, constructs the recording manager, starts the processing pipeline, initializes the saver, and then opens the streams. If no usable stream can be created, start fails. If the microphone is missing but system audio is available, the application can proceed with system audio only. If system audio fails while the microphone works, the stream manager treats that failure as non-fatal and can continue with the microphone path. Those are different degraded modes, and a user should record which one occurred rather than describing the session simply as “recorded.”
After streams open, a blank transcript still has several possible causes. The audio pipeline may be receiving samples but not enough qualifying speech for VAD to close a segment. The live detector waits for a qualifying silence, so continuous sound can keep a segment open and delay emission. A segment may be too short and be discarded before recognition. The selected model may not be loaded in the worker, or the model may return an empty or repetitive result that the Whisper cleanup heuristics remove.