Skip to content

PROGRESS.md

Latest commit

 

History

History
123 lines (109 loc) · 6.66 KB

PROGRESS.md

File metadata and controls

123 lines (109 loc) · 6.66 KB
Raw

Progress

Current milestone

Post-MVP issue #8: segmented recognition and completion semantics — complete

Completed acceptance criteria

  • SwiftPM executable product named parrot created.
  • Minimal source and test layout created.
  • README.md, AGENTS.md, PROGRESS.md, .gitignore, and Makefile added.
  • Basic --help and --version output implemented.
  • swift build succeeds.
  • swift run parrot --help succeeds.
  • swift test succeeds with three tests.
  • AVAudioEngine microphone capture implemented behind --debug-audio.
  • Microphone authorization and denial handling implemented.
  • Live RMS audio levels are routed only to STDERR.
  • SIGINT and SIGTERM stop the engine and remove the input tap.
  • Audio-level and M1 argument parsing tests added.
  • The input tap inherits the audio engine's native bus format to avoid format mismatch crashes on macOS 26.
  • Manual verification passed on a microphone-equipped Apple Silicon Mac: speech changed reported levels from approximately -50 dB to -23 dB, STDOUT contained zero bytes, and Ctrl-C exited cleanly.
  • Speech and microphone authorization are requested before recognition.
  • SFSpeechRecognizer availability is checked for the current locale.
  • Microphone buffers stream into SFSpeechAudioBufferRecognitionRequest.
  • Partial, final, and recognition error diagnostics are routed only to STDERR.
  • Recognition tasks, requests, taps, and the audio engine are cleaned up.
  • SwiftPM embeds the privacy usage descriptions in the development executable so Speech authorization can be tested before app-bundle packaging in M5.
  • Manual verification passed on a microphone-equipped Mac: partial recognition appeared on STDERR, STDOUT remained empty, and Ctrl-C exited cleanly.
  • Default parrot mode waits for one recognized utterance and prints one line.
  • --timeout, --silence-duration, and --verbose are implemented.
  • Exit codes distinguish invalid arguments, permissions, timeout, recognizer, audio input, and unexpected failures.
  • Manual verification passed for direct output, pipelines, command substitution, one-line output, and no-speech timeout.
  • --locale and strict --on-device options are implemented.
  • Arguments, exit codes, interruption, and recognizer capability checks are centralized and covered by focused tests.
  • Manual verification passed for locale selection, strict on-device behavior, no-speech timeout, and interruption.
  • make app builds dist/Parrot.app with a release executable.
  • The bundle uses the stable identifier dev.lobot.parrot and contains all required version, minimum-system, and privacy metadata.
  • The build script recreates and validates a consistent bundle structure.
  • Manual verification passed for bundled version output and one-utterance transcription on a microphone-equipped Mac.
  • App builds are signed ad-hoc by default or with SIGNING_IDENTITY when set, and signatures are verified after building and installation.
  • make install installs without sudo to ~/Applications/Parrot.app and ~/.local/bin/parrot; make uninstall removes only matching artifacts.
  • Manual verification passed for install, command discovery, version output, bundled transcription, signature verification, reinstall, and uninstall.
  • README covers installation, usage, PATH setup, permissions, privacy, troubleshooting, development, uninstall, limitations, and release checks.
  • The installer refuses to overwrite an unrelated Parrot.app.
  • The cumulative manual checklist passed for microphone permission, successful utterance, timeout, interruption, pipelines, command substitution, reinstall, uninstall, locale selection, and strict on-device behavior.
  • Launch branding is Parrot: the package and CLI are parrot, the app is Parrot.app, and the stable bundle identifier is dev.lobot.parrot.
  • Apple final results now commit internal segments instead of ending Parrot.
  • Acoustic voice activity starts and resets the silence timer independently of transcript updates.
  • Final and in-progress recognition segments are assembled with overlap and duplicate suppression.
  • Documented transient recognition errors restart a bounded number of segments; unknown and repeated errors fail explicitly.
  • The existing timeout remains the hard safety limit for the full invocation.
  • Deterministic tests cover voice activity, completion state, transcript assembly, error policy, interruption, timeout, and on-device request settings.
  • Manual long-form validation on a microphone-equipped Mac captured a multi-minute reading through many natural pauses and completed only after the configured five seconds of final silence. The transcript remained coherent, stdout contained only the combined result, and verbose stderr ended with completion reason: silence.
  • Additional microphone checks passed for one-line stdout routing, quiet-room no-speech timeout, pauses shorter and longer than the configured boundary, interruption during speech and silence, pipelines, command substitution, strict on-device behavior, and completion at the hard maximum duration.

Manual verification still required

  • Fresh destructive permission-denial resets and a disconnected/default-input transition were documented but not repeated during final validation.
  • Apple did not emit isFinal during the completed multi-minute validation run, so a live segment restart could not be reproduced and remains covered by deterministic tests.

Run the primary long-form check from a built checkout with:

./dist/Parrot.app/Contents/MacOS/parrot \
  --timeout 300 --silence-duration 5 --verbose \
  > /tmp/parrot.stdout 2> /tmp/parrot.stderr

Speak for several minutes, including pauses shorter than five seconds, then remain quiet for longer than five seconds. Expected: the command stays active through short pauses and any segment finalized transitions, exits 0 after the final pause, writes exactly one nonempty line containing the combined note to /tmp/parrot.stdout, and writes transitions ending in completion reason: silence only to /tmp/parrot.stderr.

The output, timeout, pause boundary, interruption, shell composition, strict on-device, and hard-maximum variants of this check have passed.

Known limitations

  • Voice activity uses a conservative fixed microphone-energy threshold; very quiet speech and noisy environments can affect silence detection.
  • Apple controls recognition quality and whether non-strict recognition uses network services.
  • Current local builds target Apple Silicon rather than universal binaries.

Next milestone

Review and merge issue #8. If Apple emits a live final during future testing, confirm the segment transition diagnostics and combined transcript behavior.