{"id":50546482,"url":"https://github.com/bryanlabs/echoform","last_synced_at":"2026-06-03T23:30:25.503Z","repository":{"id":359453580,"uuid":"1246148992","full_name":"bryanlabs/echoform","owner":"bryanlabs","description":"Turn whatever audio is playing on your Mac into calm, ambient visuals","archived":false,"fork":false,"pushed_at":"2026-05-22T04:26:48.000Z","size":694,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T08:45:26.132Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bryanlabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-21T23:25:39.000Z","updated_at":"2026-05-22T04:26:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bryanlabs/echoform","commit_stats":null,"previous_names":["bryanlabs/echoform"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/bryanlabs/echoform","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bryanlabs%2Fechoform","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bryanlabs%2Fechoform/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bryanlabs%2Fechoform/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bryanlabs%2Fechoform/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bryanlabs","download_url":"https://codeload.github.com/bryanlabs/echoform/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bryanlabs%2Fechoform/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33884733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-03T23:30:25.005Z","updated_at":"2026-06-03T23:30:25.497Z","avatar_url":"https://github.com/bryanlabs.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Echoform\n\n[![CI](https://github.com/bryanlabs/echoform/actions/workflows/ci.yml/badge.svg)](https://github.com/bryanlabs/echoform/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Platform](https://img.shields.io/badge/platform-macOS%2015%2B-lightgrey.svg)](#requirements)\n[![Swift](https://img.shields.io/badge/Swift-6.2-orange.svg)](https://swift.org)\n\nEchoform is a macOS app that turns whatever audio is playing on your Mac into\na calm, beautiful visualization. It taps your system audio output and renders\nit as ambient, audio-reactive visuals, so whatever you are listening to\n(music, a podcast, an audiobook, a call) you have something gentle to look at\ninstead of reaching for a feed, a game, or another screen.\n\nIt is built to hold your eyes without taking your attention: ambient, not\ninteractive; glanceable, not readable; audio-reactive, not content-competing.\nThe point is visual interest while you listen, not a second task.\n\n![Echoform in Bars mode with the Cyberpunk theme and live on-device captions](docs/screenshots/cyberpunk-captions.png)\n\n*Bars mode with the Cyberpunk theme and on-device captions.*\n\n## What it does\n\n- Captures whatever is playing through the system audio output, locally.\n- Renders it as one of six calm visual modes (bars, waveform, spectral heat,\n  pulse field, flow field, or a combined view).\n- Optionally shows a low-latency caption layer, with optional on-device\n  translation between a dozen major languages.\n- Themeable, full-screen capable, and adjustable from a right-click menu.\n\nNothing is recorded or saved. The visualizer itself makes no network calls.\nWhen captions are enabled, Apple Speech may use online recognition for\nlanguages without a local model unless **On-device Only** is turned on.\n\n## Requirements\n\n- macOS 15 or later (built and tested on macOS 26).\n- To build from source: Xcode 26 with the Swift 6.2 toolchain.\n\n## Build and install\n\nBuilding from source is the recommended way to run Echoform. You can read\nevery line first, and a build you compiled yourself is not quarantined, so it\nopens with no Gatekeeper prompt (see \"Permissions and trust\" below).\n\n```sh\ngit clone https://github.com/bryanlabs/echoform.git\ncd echoform\n./Scripts/install.sh\n```\n\nThis builds `Echoform.app`, installs it to `/Applications`, and installs an\n`echoform` launcher into `~/bin`. The build is ad-hoc signed. If you have an\nApple Development certificate it is used automatically instead, which keeps\nmacOS from re-asking for system audio access on every rebuild.\n\n- `./Scripts/package-app.sh` builds the app into `dist/` without installing.\n- `./Scripts/make-icon.sh` regenerates the app icon.\n\n## First run: grant system audio access\n\nEchoform uses Core Audio process taps to listen to the system audio already\nplaying on your Mac. macOS calls this **System Audio Recording Only** in System\nSettings.\n\n1. Launch Echoform.\n2. Approve the macOS system audio prompt if it appears.\n3. If the prompt does not appear, open System Settings ›\n   Privacy \u0026 Security › Screen \u0026 System Audio Recording.\n4. Enable **Echoform** under **System Audio Recording Only**, and authenticate\n   when macOS asks.\n5. Quit and reopen Echoform.\n\nmacOS remembers the grant, so you only do this once.\n\n## Controls\n\nRight-click anywhere on the visualizer to open the main controls menu. It\nincludes visual mode, theme, brightness, intensity, captions, spoken language,\ntranslation target, recognition mode, low-latency mode, and caption sync\noffset.\n\nKeyboard shortcuts remain available as optional accelerators:\n\n| Key      | Action                            |\n|----------|-----------------------------------|\n| `1`-`6`  | Switch visual mode                |\n| `Space`  | Pause / resume                    |\n| `F`      | Toggle full screen                |\n| `Esc`    | Leave full screen                 |\n| `[` `]`  | Decrease / increase intensity     |\n| `B`      | Cycle brightness                  |\n| `←` `→`  | Cycle theme                       |\n| `C`      | Open the theme / color panel      |\n| `T`      | Toggle captions                   |\n| `L`      | Open the captions panel           |\n| `,` `.`  | Decrease / increase sync offset   |\n| `Cmd+Q`  | Quit                              |\n\n## Visual modes\n\n1. **Bars.** Symmetric loudness and frequency bars.\n2. **Wave Ribbon.** A smooth, glowing waveform ribbon.\n3. **Spectral Heat.** A slow-scrolling spectrogram.\n4. **Pulse Field.** Breathing shapes driven by loudness and bass.\n5. **Flow Field.** A slowly flowing vector field shaped by mids and treble.\n6. **Combined.** Heat, pulse, and bars layered into one ambient view.\n\n## Captions and the delay\n\nRight-click and enable **Captions** to show a calm, low-contrast text layer in\nthe lower window. Pick **Spoken Language** and, if useful, enable **Translate**\nand choose **Translate To**.\n\n**Low Latency Captions** is on by default. In this mode Echoform shows Apple's\ncurrent partial recognition hypothesis immediately, replacing it as Apple\nrevises the text. This is tuned for listening above 1x speed, where waiting for\nfully stable words is more distracting than occasional text correction.\n\nTurning **Low Latency Captions** off switches back to the steadier delayed\ncaption history. That mode hides the newest partial word and can feel calmer,\nbut it usually trails fast podcast or audiobook playback.\n\nRecognition runs behind the audio, so **Caption Sync Offset** in the right-click\nmenu lets you tune the relationship between the captions and the visualizer\nfrom -2 to +10 seconds. Negative offsets are useful for small timing nudges,\nsuch as -0.33s. Positive offsets hold back the visualizer so captions and bars\ncan line up, but they do not delay what you hear.\n\nEchoform currently observes system audio through a Core Audio process tap. It\ndoes not act as an output device and does not route audio onward to your\nspeakers. That means a negative caption offset cannot show a word before the\nspeech recognizer has emitted it. To make heard audio itself wait for captions,\nEchoform would need a route-through audio mode built around a virtual output\ndevice or audio driver.\n\nWith translation on in low-latency mode, Echoform keeps the source-language\npartial visible immediately and updates the translated line as translation\ncatches up. Translation uses Apple's Translation framework; the first time you\nuse a language pair, macOS downloads that pair once.\n\n**On-device Only** is off by default so languages without installed local speech\nmodels still work through Apple's online speech recognition. Turn it on if you\nwant to force local recognition only.\n\n## Themes\n\nUse the right-click **Theme** menu to pick Classic, Cyberpunk (pink and\npurple), Aurora (greens), Ember (warm reds), or Custom. The **Custom Colors**\nmenu item opens the color panel with preset swatches and three color wells.\n\n## Preview mode\n\nTo see the visuals without playing audio and without granting any permission:\n\n```sh\nechoform --demo\n```\n\nAdd `--text` to start with the caption layer on. Demo mode feeds a synthetic\nsignal through the renderer, useful for trying modes, themes, and brightness.\n\n## Permissions and trust\n\nEchoform asks for two macOS permissions, and only those two.\n\n- **System Audio Recording Only.** Echoform uses a Core Audio process tap to\n  read the audio that is already playing. It never captures, shows, or saves\n  the screen or any video. Granting it is a one-time step (see \"First run\").\n- **Speech Recognition.** Requested only when you turn captions on. By default\n  Echoform allows Apple's online recognition for languages without an installed\n  local model, which makes Spanish, Korean, and other languages work without\n  extra model setup. Turn on **On-device Only** in the right-click menu if you\n  want to force local recognition.\n\nEchoform itself makes no network calls and never records, saves, or uploads\naudio, transcripts, or anything else. Audio is analyzed in memory in real time\nand then discarded. The exceptions are Apple-provided system services: macOS may\ndownload a translation language pack the first time you pick a new pair, and\nApple Speech may use online recognition when **On-device Only** is off.\n\n### Why there is no notarized download\n\nAn app that opens with no warning on any Mac has to be notarized by Apple,\nwhich requires a paid Apple Developer Program membership. Echoform is a free,\nzero-budget project and is not enrolled, so it is not notarized.\n\nThat is why building from source is the recommended path: the whole app is in\nthis repository, you can audit it, and a build you compiled locally is not\nquarantined, so it opens with no Gatekeeper prompt.\n\nIf a release attaches a pre-built `Echoform.app`, macOS blocks it on first\nlaunch because it is not notarized. To open it anyway, launch it once, then\nopen System Settings › Privacy \u0026 Security, find the note about Echoform being\nblocked, and click **Open Anyway**. Or clear the download quarantine first:\n\n```sh\nxattr -dr com.apple.quarantine /path/to/Echoform.app\n```\n\n## Project layout\n\n- `Sources/EchoformKit/` is the engine library: capture, analysis, observable\n  state, speech, and the SwiftUI renderers.\n- `Sources/Echoform/` is the app entry point.\n- `Tests/EchoformKitTests/` holds unit tests for the analysis layer.\n- `Scripts/` holds the build, sign, install, icon, and transcription benchmark\n  scripts.\n\n## Transcription benchmarks\n\nUse `Scripts/benchmark-transcribers.py` to compare candidate caption engines on\nthe same audio file. It runs Parakeet locally and can run xAI Grok STT or Groq\nWhisper when `XAI_API_KEY` or `GROQ_API_KEY` is present in the environment.\n\n```sh\nScripts/benchmark-transcribers.py sample.wav --language es --repeat 3\n```\n\nSee `docs/transcription-benchmarks.md` for the latest local benchmark notes.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbryanlabs%2Fechoform","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbryanlabs%2Fechoform","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbryanlabs%2Fechoform/lists"}