{"id":50467857,"url":"https://github.com/darkliquid/zounds","last_synced_at":"2026-06-01T08:30:52.430Z","repository":{"id":351716348,"uuid":"1208074170","full_name":"darkliquid/zounds","owner":"darkliquid","description":"Sample management","archived":false,"fork":false,"pushed_at":"2026-04-16T07:39:58.000Z","size":330,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-16T08:26:56.792Z","etag":null,"topics":["analysis","audio","management","samples","similarity"],"latest_commit_sha":null,"homepage":"","language":"Go","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/darkliquid.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-04-11T19:31:22.000Z","updated_at":"2026-04-14T18:51:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/darkliquid/zounds","commit_stats":null,"previous_names":["darkliquid/zounds"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/darkliquid/zounds","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkliquid%2Fzounds","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkliquid%2Fzounds/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkliquid%2Fzounds/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkliquid%2Fzounds/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/darkliquid","download_url":"https://codeload.github.com/darkliquid/zounds/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkliquid%2Fzounds/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33767434,"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-01T02:00:06.963Z","response_time":115,"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":["analysis","audio","management","samples","similarity"],"created_at":"2026-06-01T08:30:51.221Z","updated_at":"2026-06-01T08:30:52.418Z","avatar_url":"https://github.com/darkliquid.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zounds\n\n`zounds` is a Go toolkit and CLI for scanning, analyzing, tagging, clustering, deduplicating, transforming, and browsing sound-sample libraries.\n\nThe codebase is library-first: the reusable logic lives under `pkg/`, and the `zounds` CLI layers workflows on top of it.\n\n## Current capabilities\n\n- scan directories for common audio formats\n- decode WAV, AIFF, FLAC, MP3, and OGG/Vorbis\n- analyze metadata, spectrum, spectral contrast/bandwidth, chroma, tonnetz, HPSS ratios, tempo, pitch, key, MFCC, loudness, ADSR-style dynamics, formants, splice points, waveform shape, harmonicity, quality metrics, and perceptual fingerprints\n- derive tags from paths, embedded metadata, configurable expr-based rule files, local feature-vector classification, optional CLAP classifier services, and optional OpenAI-compatible LLM inference\n- find exact and perceptual duplicates\n- compute similarity, k-means clusters, DBSCAN clusters, and 2D PCA/t-SNE projections\n- convert sample rate, channel layout, output format, and loudness\n- rename and organization-plan samples from templates, tags, and clusters\n- browse and preview indexed samples from the CLI\n- serve an embedded web UI with API endpoints, tag cloud, sample browser, preview playback, and cluster bubble view\n\n## CLI\n\nImplemented commands:\n\n```text\nzounds scan\nzounds analyze\nzounds tag\nzounds similar\nzounds cluster\nzounds dedup\nzounds convert\nzounds rename\nzounds export\nzounds info\nzounds play\nzounds browse\nzounds serve\n```\n\nExamples:\n\n```bash\nzounds scan ~/Samples\nzounds analyze --all\nzounds tag --auto --rule-file ./rules.json --clap-model-dir ./models/clap\nzounds similar --threshold 0.85 --limit 20 ./Samples/Kicks/punch.wav ./Samples/Snares/crack.wav\nzounds cluster --method kmeans --k 12 --projection tsne\nzounds dedup --perceptual --threshold 8\nzounds rename --template '{{join .Tags \"_\"}}_{{slug .Stem}}.{{.Extension}}' --dry-run\nzounds serve --port 8080\n```\n\nBy default, the CLI stores its SQLite database at `$XDG_DATA_HOME/zounds/zounds.db`, falling back to `~/.local/share/zounds/zounds.db` when `XDG_DATA_HOME` is unset. Use `--db` to override it.\n\nFor local CLAP tagging, download `audio_model.onnx`, `text_model.onnx`, and `tokenizer.json` from [Xenova/clap-htsat-unfused](https://huggingface.co/Xenova/clap-htsat-unfused), place them in a directory such as `./models/clap`, and pass that directory with `--clap-model-dir`. You also need the ONNX Runtime shared library available on your system, or provide its path with `--clap-lib`.\n\n## Tagging rules\n\n`zounds tag --auto` can load a JSON rule file with `--rule-file`. Rules are evaluated with the [`expr`](https://expr-lang.org/) language against this environment:\n\n- `Metrics[\"name\"]` for numeric analysis outputs such as `frequency_hz`, `spectral_flux`, `loop_confidence`, or `spectral_centroid_hz`\n- `Attributes[\"name\"]` for string attributes such as `key`, `note_name`, `format`, or embedded metadata values\n- `Sample.Path`, `Sample.RelativePath`, `Sample.FileName`, `Sample.Extension`, `Sample.Format`, and `Sample.SizeBytes` for explicit file-aware rules\n\nEach rule defines a tag, an expression, and optional `confidence` and `source` fields:\n\n```json\n{\n  \"rules\": [\n    {\n      \"tag\": \"cyberpunk\",\n      \"expr\": \"Metrics[\\\"spectral_flux\\\"] \u003e 0.1 \u0026\u0026 Attributes[\\\"mode\\\"] == \\\"minor\\\"\",\n      \"confidence\": 0.9\n    }\n  ]\n}\n```\n\nUse it during auto-tagging:\n\n```bash\nzounds scan ~/Samples\nzounds tag --auto --rule-file ./rules.json\n```\n\nExample rule file with both analysis-driven and path-aware tags:\n\n```json\n{\n  \"rules\": [\n    {\n      \"tag\": \"sub\",\n      \"expr\": \"Metrics[\\\"frequency_hz\\\"] \u003e 0 \u0026\u0026 Metrics[\\\"frequency_hz\\\"] \u003c 120 \u0026\u0026 Metrics[\\\"confidence\\\"] \u003e 0.5\",\n      \"confidence\": 0.75\n    },\n    {\n      \"tag\": \"didgeridoo\",\n      \"expr\": \"Sample.RelativePath contains \\\"Didgeridoo Loops\\\"\",\n      \"source\": \"rules\"\n    },\n    {\n      \"tag\": \"oneshot\",\n      \"expr\": \"\\\"loop_confidence\\\" in Metrics \u0026\u0026 Metrics[\\\"loop_confidence\\\"] \u003c 0.35\"\n    }\n  ]\n}\n```\n\nThis is the recommended way to tag from folder or filename conventions. Generic path token extraction is noisy, so keep path-based tagging explicit in rules instead of relying on automatic path tokenization.\n\n## Library layout\n\n```text\ncmd/zounds/commands  Cobra command implementations\npkg/analysis         reusable analyzers and feature-vector building\npkg/audio            PCM buffer, codecs, registry, playback\npkg/cluster          similarity, k-means, DBSCAN, PCA and t-SNE projection\npkg/convert          resampling, channel conversion, transcoding, normalization\npkg/core             shared domain types and interfaces\npkg/db               SQLite connection, migrations, repository helpers\npkg/dedup            exact and perceptual dedup logic\npkg/rename           template rename and organization planning\npkg/scanner          recursive audio file discovery\npkg/tags             path, metadata, rule, local, CLAP, and LLM taggers\nweb                  embedded HTTP server and static web UI\n```\n\n## Web UI\n\n`zounds serve` starts the embedded HTTP server and frontend.\n\nAvailable API routes include:\n\n```text\nGET /api/health\nGET /api/samples\nGET /api/samples?q=...\nGET /api/samples?tag=...\nGET /api/samples/:id\nGET /api/samples/:id/audio\nGET /api/tags\nGET /api/tags/:name/samples\nGET /api/clusters\nGET /api/clusters?projection=tsne\nGET /api/clusters/:id\n```\n\n## Development\n\n```bash\nmake tidy\nmake fmt\nmake test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarkliquid%2Fzounds","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdarkliquid%2Fzounds","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarkliquid%2Fzounds/lists"}