{"id":50956664,"url":"https://github.com/rryam/musaverakit","last_synced_at":"2026-06-18T08:01:19.804Z","repository":{"id":364664722,"uuid":"1263257010","full_name":"rryam/MusaveraKit","owner":"rryam","description":"App-friendly Swift APIs for Apple's on-device Music Understanding framework.","archived":false,"fork":false,"pushed_at":"2026-06-14T00:05:34.000Z","size":87,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T01:14:59.344Z","etag":null,"topics":["audio-analysis","ios","macos","music-understanding","on-device","swift","swift-package","tvos","visionos","watchos","wwdc26"],"latest_commit_sha":null,"homepage":"https://github.com/rryam/MusaveraKit","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/rryam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"rryam"}},"created_at":"2026-06-08T19:23:19.000Z","updated_at":"2026-06-13T23:58:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rryam/MusaveraKit","commit_stats":null,"previous_names":["rryam/musaverakit"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/rryam/MusaveraKit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rryam%2FMusaveraKit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rryam%2FMusaveraKit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rryam%2FMusaveraKit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rryam%2FMusaveraKit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rryam","download_url":"https://codeload.github.com/rryam/MusaveraKit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rryam%2FMusaveraKit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34481332,"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-18T02:00:06.871Z","response_time":128,"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":["audio-analysis","ios","macos","music-understanding","on-device","swift","swift-package","tvos","visionos","watchos","wwdc26"],"created_at":"2026-06-18T08:01:18.215Z","updated_at":"2026-06-18T08:01:19.793Z","avatar_url":"https://github.com/rryam.png","language":"Swift","funding_links":["https://github.com/sponsors/rryam"],"categories":[],"sub_categories":[],"readme":"# MusaveraKit\n\nSmall, app-friendly Swift APIs for on-device music analysis with Apple's\n[Music Understanding](https://developer.apple.com/documentation/MusicUnderstanding)\nframework.\n\n[![Repository checks](https://github.com/rryam/MusaveraKit/actions/workflows/repository-checks.yml/badge.svg)](https://github.com/rryam/MusaveraKit/actions/workflows/repository-checks.yml)\n[![Swift 6.4](https://img.shields.io/badge/Swift-6.4-F05138.svg?logo=swift\u0026logoColor=white)](https://www.swift.org)\n[![Apple platforms 27+](https://img.shields.io/badge/Apple%20platforms-27%2B-000000.svg?logo=apple\u0026logoColor=white)](#requirements)\n[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n```swift\nimport AVFoundation\nimport MusaveraKit\n\nlet asset = AVURLAsset(url: audioURL)\nlet analysis = try await Musavera.analyze(asset: asset)\n\nprint(analysis.beatsPerMinute as Any)\nprint(analysis.key?.primarySignature?.musaveraDescription as Any)\nprint(analysis.sectionCount)\n```\n\nMusaveraKit keeps Music Understanding's native result types available while\nremoving repetition around session setup, focused analysis, optional results,\nand common timeline lookups.\n\n## Early Access\n\nMusic Understanding was introduced at WWDC26 and remains a beta framework.\nMusaveraKit tracks that SDK closely, so APIs and platform requirements may\nchange during the beta cycle.\n\nFull compilation and runtime testing require Xcode 27 and an operating-system\n27 runtime. GitHub's current hosted runners do not include that SDK, so CI\nperforms repository, manifest, privacy, and Swift syntax validation. Complete\nbuilds and tests are run locally with Xcode 27.\n\n## Requirements\n\n- Xcode 27 beta or later\n- Swift 6.4 or later\n- iOS 27.0+\n- macOS 27.0+\n- tvOS 27.0+\n- watchOS 27.0+\n- visionOS 27.0+\n\n## Installation\n\nAdd MusaveraKit with Swift Package Manager:\n\n```swift\ndependencies: [\n    .package(\n        url: \"https://github.com/rryam/MusaveraKit.git\",\n        from: \"0.2.0\"\n    )\n]\n```\n\nThen add the product to your target:\n\n```swift\n.product(name: \"MusaveraKit\", package: \"MusaveraKit\")\n```\n\n## Analyze Audio\n\nCreate an `AVAsset` for audio your app can access, then request all supported\nanalysis:\n\n```swift\nlet asset = AVURLAsset(url: audioURL)\nlet analysis = try await Musavera.analyze(asset: asset)\n```\n\nThe returned `MusaveraAnalysis` exposes Music Understanding's session result\nand convenient accessors for:\n\n- rhythm, beats, bars, and beats per minute\n- musical key\n- loudness\n- perceived pace\n- sections, phrases, and segments\n- vocal, drum, bass, and other instrument activity\n\nMusic Understanding performs its analysis on device. MusaveraKit does not\nupload audio, download Apple Music content, or require MusadoraKit.\n\n## Request Only What You Need\n\nSelected analysis avoids unnecessary work:\n\n```swift\nlet analysis = try await Musavera.analyze(\n    asset: asset,\n    options: [.rhythm, .key, .structure]\n)\n```\n\nUse a focused helper when one result is enough:\n\n```swift\nlet rhythm = try await Musavera.rhythm(for: asset)\nlet key = try await Musavera.key(for: asset)\nlet loudness = try await Musavera.loudness(for: asset)\nlet pace = try await Musavera.pace(for: asset)\nlet structure = try await Musavera.structure(for: asset)\nlet instruments = try await Musavera.instrumentActivity(for: asset)\n```\n\nPassing an empty option set throws `MusaveraKitError.emptyAnalysisSet`. A\nfocused helper throws `MusaveraKitError.missingResult` if the framework does not\nreturn its requested result.\n\n## Analyze Streaming Audio\n\nCreate a session from any nonthrowing asynchronous sequence of read-only PCM\nbuffers:\n\n```swift\nlet session = MusaveraStreamingSession(audioProvider: audioBuffers)\n\nasync let analysis = session.analyze()\n\nfor try await loudness in session.loudnessResults {\n    updateMeter(with: loudness)\n}\n\nlet completedAnalysis = try await analysis\n```\n\nLoudness results arrive while the provider yields audio. The complete\n`MusaveraAnalysis`, including key, rhythm, structure, pace, and instrument\nactivity, becomes available after the provider finishes.\n\n## Timeline Helpers\n\nMusaveraKit adds small conveniences for playback-synchronized interfaces:\n\n```swift\nlet signature = analysis.keySignature(at: playbackTime)\nlet nearestBeat = rhythm.nearestBeat(to: playbackTime)\nlet nearestBar = rhythm.nearestBar(to: playbackTime)\n\nlet section = structure.section(containing: playbackTime)\nlet phrase = structure.phrase(containing: playbackTime)\nlet segment = structure.segment(containing: playbackTime)\n```\n\nInstrument activity is available as both detected ranges and timed values:\n\n```swift\nlet vocalRanges = instruments.vocalRanges\nlet drumRanges = instruments.drumRanges\nlet bassRanges = instruments.bassRanges\nlet otherRanges = instruments.otherRanges\n\nlet vocalActivity = instruments.activity(for: .vocal)\n```\n\n## MusadoraKit and MusaveraKit\n\n[MusadoraKit](https://github.com/rryam/MusadoraKit) simplifies MusicKit and\nApple Music API workflows such as catalog search, library access, and playback.\nMusaveraKit analyzes audio assets for musical characteristics. The packages are\nindependent so apps can adopt either one, while remaining complementary for\nmusic discovery, playback, and visualization experiences.\n\n## Musavera Lab\n\n[`Examples/MusaveraLab`](Examples/MusaveraLab) is a signed macOS 27 sample app\nthat composes first-party MusicKit with MusaveraKit. It searches Apple Music,\nshows catalog artwork, downloads a song's 30-second preview for local analysis,\noffers separate full-song playback, and renders synchronized key, rhythm,\nstructure, pace, instrument, and loudness views. The complete native\nMusicUnderstanding result can also be exported as formatted JSON. Its Live\nStream workspace analyzes microphone PCM, draws realtime loudness, and\ncompletes the remaining musical analysis when capture stops.\n\nThe activity charts adapt from one to four columns, so a large window can show\nall four instrument activity timelines side by side.\n\n## Development\n\nSelect Xcode 27 if it is not already active:\n\n```bash\nexport DEVELOPER_DIR=/path/to/Xcode-beta.app/Contents/Developer\n```\n\nRun the complete test suite:\n\n```bash\nswift test\n```\n\nBuild an Apple-platform target:\n\n```bash\nxcodebuild \\\n  -scheme MusaveraKit \\\n  -destination 'generic/platform=iOS' \\\n  -derivedDataPath .build/xcode \\\n  build\n```\n\nRun checks that also work before the Xcode 27 SDK is available:\n\n```bash\nScripts/validate-repository.sh\n```\n\nGenerate DocC documentation:\n\n```bash\nswift package generate-documentation --target MusaveraKit\n```\n\n## Documentation and Resources\n\n- [Getting Started](Sources/MusaveraKit/Documentation.docc/GettingStarted.md)\n- [Working with Analysis Results](Sources/MusaveraKit/Documentation.docc/AnalysisResults.md)\n- [Music Understanding documentation](https://developer.apple.com/documentation/MusicUnderstanding)\n- [Meet the Music Understanding framework](https://developer.apple.com/videos/play/wwdc2026/253/)\n- [Creating visuals using analysis results](https://developer.apple.com/documentation/MusicUnderstanding/create-visuals-using-musicunderstanding-analysis-results)\n\n## Project Policies\n\n- Read [CONTRIBUTING.md](CONTRIBUTING.md) before proposing a change.\n- Use [SUPPORT.md](SUPPORT.md) to choose the right reporting channel.\n- Report vulnerabilities according to [SECURITY.md](SECURITY.md).\n- Follow the [Code of Conduct](CODE_OF_CONDUCT.md).\n- See [CONTRIBUTORS.md](CONTRIBUTORS.md) for project attribution.\n- Review [CHANGELOG.md](CHANGELOG.md) for notable changes.\n\n## License\n\nMusaveraKit is available under the MIT License. See [LICENSE](LICENSE).\n\nApple, Apple Music, MusicKit, and related marks are trademarks of Apple Inc.\nMusaveraKit is an independent open-source project and is not affiliated with or\nendorsed by Apple.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frryam%2Fmusaverakit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frryam%2Fmusaverakit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frryam%2Fmusaverakit/lists"}