{"id":50744101,"url":"https://github.com/cloud-oc/heartecho","last_synced_at":"2026-06-10T19:01:04.570Z","repository":{"id":362280503,"uuid":"1258054660","full_name":"cloud-oc/Heartecho","owner":"cloud-oc","description":"Heartecho 是一个原生 macOS 音频路由工作台，用来创建虚拟音频设备、把应用或硬件输入映射到输出通道、监看电平。Heartecho is a native macOS audio-routing workbench for creating virtual audio devices, mapping app or hardware inputs to output channels, monitoring levels.Heartecho は、仮想オーディオデバイスの作成、アプリまたはハードウェア入力から出力チャンネルへのルーティング、レベル監視。","archived":false,"fork":false,"pushed_at":"2026-06-03T12:33:06.000Z","size":176,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-03T13:16:14.987Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloud-oc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-06-03T08:33:49.000Z","updated_at":"2026-06-03T12:33:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cloud-oc/Heartecho","commit_stats":null,"previous_names":["cloud-oc/heartecho"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/cloud-oc/Heartecho","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-oc%2FHeartecho","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-oc%2FHeartecho/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-oc%2FHeartecho/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-oc%2FHeartecho/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloud-oc","download_url":"https://codeload.github.com/cloud-oc/Heartecho/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-oc%2FHeartecho/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34165482,"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-10T02:00:07.152Z","response_time":89,"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-10T19:01:03.104Z","updated_at":"2026-06-10T19:01:04.558Z","avatar_url":"https://github.com/cloud-oc.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Heartecho\n\n[English](README.md) | [简体中文](docs/README.zh-CN.md) | [日本語](docs/README.ja.md)\n\nHeartecho is a native macOS audio-routing workbench for creating virtual audio devices, mapping app or hardware inputs to output channels, monitoring levels, and packaging the supporting Core Audio HAL driver pieces needed for real system integration.\n\nThe product direction is inspired by tools like Rogue Amoeba Loopback, but this repository is currently an engineering preview: the SwiftUI app, routing model, diagnostics, helper runtime, installer scripts, and C HAL driver skeleton are present; a polished signed/notarized production release still depends on Developer ID signing, notarization, and full installed-driver validation.\n\n## Product Snapshot\n\n- Native macOS SwiftUI/AppKit app for routing graph configuration.\n- Core routing model for virtual devices, sources, channel maps, monitors, gains, mutes, presets, and graph validation.\n- Runtime audio scaffolding for app taps, hardware input capture, sample-rate conversion, monitor playback, meters, and HAL shared-memory publication.\n- C HAL Audio Server Driver skeleton plus Swift bridge, bundle generation, verification, install, uninstall, and diagnostics scripts.\n- Release packaging pipeline for app bundle, HAL driver bundle, helper LaunchAgent, installer package, uninstaller package, distribution package, and JSON release manifest.\n\nDeeper implementation notes live in [docs/architecture.md](docs/architecture.md), [docs/feature-map.md](docs/feature-map.md), [docs/hal-driver.md](docs/hal-driver.md), and [docs/implementation-plan.md](docs/implementation-plan.md).\n\n## Requirements\n\n- macOS 14 or newer.\n- Swift 6 toolchain.\n- Xcode 16 or newer for release builds, signing, package tooling, and HAL driver work. Command Line Tools are enough for some local SwiftPM development tasks.\n- Python with Pillow for icon generation. The GitHub Actions workflow creates a local virtual environment automatically.\n\n## Download\n\nMost users should download the latest `Heartecho-\u003cversion\u003e.dmg` from [GitHub Releases](https://github.com/cloud-oc/Heartecho/releases/latest).\n\nOpen the DMG, then run `Install Heartecho.pkg`. The package installs the app plus the required system audio components. The Release also includes raw `.pkg` files and `release-manifest.json` for debugging, automation, and artifact verification; the DMG is the recommended user-facing download.\n\n### Gatekeeper Notice\n\nThe current community release is unsigned and not notarized because the project does not yet have an Apple Developer Program account. macOS may show \"Apple cannot verify\" or \"damaged\" warnings on first install.\n\nIf the installer is blocked:\n\n1. Open the DMG and run `Install Heartecho.pkg`.\n2. Open `System Settings \u003e Privacy \u0026 Security`.\n3. Click `Open Anyway` for `Install Heartecho.pkg`.\n4. If macOS still blocks it after installation, remove the quarantine attribute:\n\n```sh\nsudo xattr -r -d com.apple.quarantine /Applications/Heartecho.app\nsudo xattr -r -d com.apple.quarantine \"/Library/Audio/Plug-Ins/HAL/Heartecho.driver\"\n```\n\nOnly use this for releases downloaded from this repository. This is a community workaround, not a replacement for Apple notarization.\n\n### Homebrew\n\nInstall from this repository's third-party cask:\n\n```sh\nbrew tap cloud-oc/Heartecho https://github.com/cloud-oc/Heartecho\nbrew install --cask --no-quarantine heartecho\n```\n\nUninstall:\n\n```sh\nbrew uninstall --cask heartecho\n```\n\n## Quick Start\n\nRun the app from Swift Package Manager:\n\n```sh\nswift run Heartecho\n```\n\nRun diagnostics without making system changes:\n\n```sh\nCLANG_MODULE_CACHE_PATH=.build/clang-module-cache \\\nswift run --disable-sandbox HeartechoDiagnostics --skip-shared-memory\n```\n\nBuild and verify a local app bundle:\n\n```sh\nscripts/build-icons.sh\nscripts/build-app-bundle.sh debug\nscripts/verify-app-bundle.sh\n```\n\nBuild release artifacts locally:\n\n```sh\nscripts/build-release-artifacts.sh --configuration release\n```\n\nThe release artifact command writes the user-facing DMG and packages to `build/pkg/`, and writes the release manifest to `build/release-manifest.json`.\n\n## GitHub Release Automation\n\n`VERSION` is the source of truth for GitHub Release versioning. The workflow in [.github/workflows/release.yml](.github/workflows/release.yml) runs on pushes to `main` and on manual dispatch.\n\nThe release job runs on `macos-15` and selects Xcode 16.4 so the Swift 6 package tools version in [Package.swift](Package.swift) is supported. `scripts/check-swift-toolchain.sh` fails early with a readable message if a runner falls back to an older Swift toolchain.\n\nBy default, the workflow publishes a `community-unsigned` release. Manual workflow dispatch can choose `notarized` after Developer ID certificates and Apple notarization credentials are available.\n\nOn a successful run, the workflow:\n\n1. Reads `VERSION`.\n2. Installs the Python icon-build dependency.\n3. Builds and verifies the app, HAL driver, installer package, uninstaller package, distribution package, user-facing DMG, and manifest.\n4. In `notarized` mode, imports Developer ID certificates, signs the deliverables, submits them for Apple notarization, and staples the accepted tickets.\n5. Creates `v$(cat VERSION)` when missing, or updates the existing Release assets with `--clobber`.\n\nGitHub Secrets required for `notarized` mode:\n\n- `DEVELOPER_ID_APPLICATION_CERTIFICATE_BASE64`: base64-encoded `.p12` for the Developer ID Application certificate.\n- `DEVELOPER_ID_INSTALLER_CERTIFICATE_BASE64`: base64-encoded `.p12` for the Developer ID Installer certificate.\n- `DEVELOPER_ID_APPLICATION_CERTIFICATE_PASSWORD` and `DEVELOPER_ID_INSTALLER_CERTIFICATE_PASSWORD`, or a shared `DEVELOPER_ID_CERTIFICATE_PASSWORD`.\n- `DEVELOPER_ID_APPLICATION_IDENTITY`: for example `Developer ID Application: Your Name (TEAMID)`.\n- `DEVELOPER_ID_INSTALLER_IDENTITY`: for example `Developer ID Installer: Your Name (TEAMID)`.\n- `NOTARY_APPLE_ID`: Apple Developer account email.\n- `NOTARY_TEAM_ID`: Apple Developer Team ID.\n- `NOTARY_PASSWORD`: app-specific password for Apple notarization.\n- `SIGNING_KEYCHAIN_PASSWORD`: optional temporary CI keychain password. The import script generates one when this is omitted.\n\nFor local publishing after GitHub CLI authentication:\n\n```sh\nscripts/build-release-artifacts.sh --configuration release\nscripts/publish-github-release.sh\n```\n\nUse `scripts/build-release-artifacts.sh --configuration release --require-notarized` only when Developer ID signing and Apple notarization credentials are configured.\n\n## System Integration\n\nHeartecho cannot become a Loopback-equivalent product as a plain sandboxed app. Virtual devices require a Core Audio HAL Audio Server Driver installed in a system or user plug-in location. Per-application capture requires macOS process taps and user-granted audio capture permission. Hardware input capture requires microphone permission.\n\nUse the install, uninstall, validation, and recovery scripts as dry runs first:\n\n```sh\nscripts/install-heartecho.sh --wait 30\nscripts/uninstall-heartecho.sh --unload-helper --reload-core-audio\nscripts/validate-installation.sh --wait 30\nscripts/validate-installed-audio.sh --iterations 3 --wait 30\n```\n\nAdd `--execute` only when signing, notarization, install locations, and local system impact are understood.\n\n## Project Map\n\n- `Sources/HeartechoApp`: native configuration and monitoring app.\n- `Sources/HeartechoCore`: product model, presets, persistence, and graph validation.\n- `Sources/HeartechoAudio`: discovery, capture scaffolds, routing runtime, mixer, monitor playback, HAL publication, and diagnostics helpers.\n- `Sources/HeartechoHelper`: command-line helper for graph bootstrap and HAL config/audio publication.\n- `Sources/HALDriverStub` and `Sources/HALDriverC`: Swift bridge and C HAL driver skeleton.\n- `scripts`: build, verify, sign, notarize, install, uninstall, validate, recover, release, and publishing automation.\n- `docs`: architecture, HAL, feature, and implementation references.\n\n## Maintenance Model\n\nKeep this README as the product entry point. Put detailed engineering notes in `docs/`, keep release behavior in scripts, and update the three localized README files together when product-facing behavior changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud-oc%2Fheartecho","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloud-oc%2Fheartecho","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud-oc%2Fheartecho/lists"}