{"id":50306814,"url":"https://github.com/steppschuh/ai-music-tagger-client","last_synced_at":"2026-05-28T17:01:41.928Z","repository":{"id":359960402,"uuid":"1152998985","full_name":"Steppschuh/ai-music-tagger-client","owner":"Steppschuh","description":"AI-powered music metadata enrichment tool","archived":false,"fork":false,"pushed_at":"2026-05-24T09:46:03.000Z","size":11701,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T11:26:02.772Z","etag":null,"topics":["audio","id3","mp3","music","tagger"],"latest_commit_sha":null,"homepage":"https://ai-music-tagger.web.app/","language":"TypeScript","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/Steppschuh.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-08T18:45:22.000Z","updated_at":"2026-05-24T09:45:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Steppschuh/ai-music-tagger-client","commit_stats":null,"previous_names":["steppschuh/ai-music-tagger-client"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/Steppschuh/ai-music-tagger-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steppschuh%2Fai-music-tagger-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steppschuh%2Fai-music-tagger-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steppschuh%2Fai-music-tagger-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steppschuh%2Fai-music-tagger-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Steppschuh","download_url":"https://codeload.github.com/Steppschuh/ai-music-tagger-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steppschuh%2Fai-music-tagger-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33617718,"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-05-28T02:00:06.440Z","response_time":99,"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","id3","mp3","music","tagger"],"created_at":"2026-05-28T17:01:41.080Z","updated_at":"2026-05-28T17:01:41.919Z","avatar_url":"https://github.com/Steppschuh.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Music Tagger Client\n\nA desktop companion and CLI utility that leverages AI to analyze audio files, extract detailed music metadata, and write it directly to your music library's ID3 tags.\n\nThe AI analysis is performed by the [AI Music Tagger API](https://ai-music-tagger.web.app). An API key is required to use this service, as the underlying audio analysis requires significant compute resources and cannot be provided for free.\n\n\u003e [!NOTE]\n\u003e **Project Status \u0026 Expectations**\n\u003e This is a personal side project in its early development stages. **The majority of this codebase was written by AI coding assistants** under human direction. Please expect rough edges and don't treat it as a quality reference for production code.\n\n---\n\n## 📥 Download\n\nReady-to-use desktop installers for all major platforms can be downloaded directly from the **[Latest GitHub Releases Page](https://github.com/Steppschuh/ai-music-tagger-client/releases/latest)**.\n\n### Which file should I download?\n*   **macOS (Apple Silicon)**: Download the `.dmg` file ending with `-macOS-Apple-Silicon.dmg` (for M1/M2/M3 chip Macs).\n*   **Windows**: Download the `.exe` file ending with `-Windows-Setup.exe` (run it to install the application).\n*   **Linux**: Download the `.deb` file (for Ubuntu/Debian) or `.rpm` file (for Fedora/RedHat).\n\n---\n\n## 🚀 Features\n\n- **AI-Powered Analysis**: Extracts descriptive metadata (genres, moods, vibes, lyrical themes, ...) and structural/performance details (phrasing type, suitable cue points, and multi-stem audio suitability).\n- **Direct ID3 Tagging**: Writes analyzed metadata directly to files (MP3, FLAC, M4A, etc.) using `node-id3`.\n- **Sidecar JSON Caching**: Automatically saves the high-fidelity AI output in a `-analysis.json` file next to each audio track. This prevents duplicate API calls and lets you re-tag your music with different strategies without re-analyzing.\n- **Dual Interfaces**: Contains both a cross-platform desktop UI (Electron \u0026 React) and a developer-friendly Command Line Interface (CLI).\n- **Customizable Tag Strategies**: Configure how the app merges AI findings with your existing tags (e.g. keeping existing tags, merging new ones, or complete overwrites).\n- **Comment Strategies**: Choose what to write to the ID3 Comment field: standard summaries, structured hashtags, raw tags, or combined options.\n\n---\n\n## 🛠 Technology Stack\n\n- **Desktop Shell**: [Electron](https://www.electronjs.org/) (Main process handles files and API requests for security and stability)\n- **Frontend**: [React](https://react.dev/) + [Vite](https://vitejs.dev/) + [Tailwind CSS](https://tailwindcss.com/) + [Shadcn UI](https://ui.shadcn.com/)\n- **CLI Tooling**: [yargs](https://github.com/yargs/yargs) + [ts-node](https://typestrong.org/ts-node/)\n- **State \u0026 Validation**: [TanStack Query](https://tanstack.com/query/latest) + [Zod](https://zod.dev/)\n- **Audio Logic**: [node-id3](https://github.com/Zazama/node-id3) for tag operations\n- **Distribution**: [Electron Forge](https://www.electronforge.io/) for bundling and code signing\n\n---\n\n## 📦 Getting Started\n\n### Prerequisites\n\n- [Node.js](https://nodejs.org/) (v18.x or later recommended)\n- [npm](https://www.npmjs.com/)\n\n### Installation\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/steppschuh/ai-music-tagger-client-electron.git\n   cd ai-music-tagger-client-electron\n   ```\n\n2. Install dependencies:\n   ```bash\n   npm install\n   ```\n\n3. Configure your environment variables:\n   Copy `.env.example` to `.env` and fill in your RapidAPI credentials and settings (required for local builds/runs).\n\n---\n\n## 💻 Running the App\n\n### Desktop Interface (GUI)\nStart the application in development mode with hot-reloading:\n```bash\nnpm start\n```\n\n### Command Line Interface (CLI)\nRun the CLI using `ts-node`:\n```bash\n# Display help and commands\nnpm run cli -- --help\n\n# Analyze a single track or folder\nnpm run cli -- analyze \"/path/to/music/track.mp3\"\n```\n\n---\n\n## 🏗 Building \u0026 Packaging\n\nTo bundle the desktop application for your host platform:\n```bash\nnpm run package\n```\n\nTo build installers and distributables (e.g. `.dmg` on macOS, `.exe` on Windows):\n```bash\nnpm run make\n```\n\n\u003e [!TIP]\n\u003e Code signing and notarization credentials for macOS are parsed from your local `.env` file during the build process using custom env-loaders in `forge.config.ts`.\n\n---\n\n## 📁 Key Directories \u0026 Files\n\n- `src/main.ts`: Electron Main process (file operations, security, IPC).\n- `src/preload.ts`: IPC bridge, keeping file/network operations strictly isolated.\n- `src/renderer/`: The React-based dashboard UI.\n- `src/services/`: Core logic (tagging, schemas, settings) shared by both GUI and CLI.\n- `bin/cli.ts`: Entry point for the CLI tool.\n- `AGENTS.md`: Technical ground truth for developers and AI assistants.\n- `MEMORY.md`: Chronological log of major architectural decisions and integration details.\n\n---\n\n## 🤖 Developer \u0026 AI Agent Context\n\nThis repository is optimized for AI-assisted development. If you are working on this project with an AI assistant, direct them to read:\n1. [AGENTS.md](file:///Users/steppschuh/Documents/Projects/Steppschuh/ai-music-tagger-client-electron/AGENTS.md) — The strict rules, naming standards, and constraints of the repository.\n2. [MEMORY.md](file:///Users/steppschuh/Documents/Projects/Steppschuh/ai-music-tagger-client-electron/MEMORY.md) — Architectural decisions, backend specifications, and known edge-cases.\n\n---\n\n## 📄 License\n\nThis project is licensed under the [GPL-3.0 License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteppschuh%2Fai-music-tagger-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsteppschuh%2Fai-music-tagger-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteppschuh%2Fai-music-tagger-client/lists"}