{"id":30587284,"url":"https://github.com/ocelotko/clean-tunes","last_synced_at":"2025-08-29T12:08:20.909Z","repository":{"id":307667817,"uuid":"1030290796","full_name":"ocelotko/clean-tunes","owner":"ocelotko","description":"A Python script that organizes and tags both MP3 and WAV audio files using the Acoustid API.","archived":false,"fork":false,"pushed_at":"2025-08-01T12:10:41.000Z","size":1513,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-01T14:37:51.470Z","etag":null,"topics":["mp3","python","script","wav"],"latest_commit_sha":null,"homepage":"","language":"Python","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/ocelotko.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}},"created_at":"2025-08-01T11:48:30.000Z","updated_at":"2025-08-01T12:11:24.000Z","dependencies_parsed_at":"2025-08-01T14:37:53.246Z","dependency_job_id":"7c8d2a0e-ce35-4c12-920c-d3f4d7064a47","html_url":"https://github.com/ocelotko/clean-tunes","commit_stats":null,"previous_names":["ocelotko/clean-tunes"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ocelotko/clean-tunes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ocelotko%2Fclean-tunes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ocelotko%2Fclean-tunes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ocelotko%2Fclean-tunes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ocelotko%2Fclean-tunes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ocelotko","download_url":"https://codeload.github.com/ocelotko/clean-tunes/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ocelotko%2Fclean-tunes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272680840,"owners_count":24975353,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-29T02:00:10.610Z","response_time":87,"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":["mp3","python","script","wav"],"created_at":"2025-08-29T12:08:20.196Z","updated_at":"2025-08-29T12:08:20.901Z","avatar_url":"https://github.com/ocelotko.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Clean Tunes\n\nThis Python script helps you clean up your music library by automatically identifying **MP3** and **WAV** files, fetching their metadata, and renaming them. It uses the **Acoustid API** and audio fingerprinting to ensure accurate song identification, even on files with missing or incorrect tags.\n\n---\n\n## Features\n\n- **Automatic Tagging**: Uses audio fingerprints to accurately identify your songs.\n- **Metadata Updates**: Writes artist, title, album, and year directly to your music file's ID3 tags.\n- **File Renaming**: Renames files to a consistent format (`Artist - Title.mp3` or `Artist - Title.wav`).\n- **Cross-Platform**: Works on Windows and Linux.\n- **Multi-Format Support**: Processes both **MP3** and **WAV** files.\n\n---\n\n## Prerequisites\n\nBefore you can run the script, you'll need the following:\n\n- **Python 3** installed on your system.\n- **An Acoustid API Key**.\n- The **`fpcalc`** executable, which is used by the Acoustid library to generate audio fingerprints. **For Windows users, `fpcalc.exe` is already included in this repository.**\n\n---\n\n## Step 1: Get Your Acoustid API Key\n\n1.  Go to the [Acoustid website](https://acoustid.org/).\n2.  Create a free account or log in.\n3.  Navigate to the **\"API Keys\"** section.\n4.  Generate a new API key and copy it.\n\n---\n\n## Step 2: Install Dependencies\n\nYou'll need to install the required Python libraries and, for Linux users, the `fpcalc` tool.\n\n### On Windows\n\n1.  **Install Python Libraries**: Open a command prompt and run the following command:\n    ```bash\n    pip install acoustid mutagen\n    ```\n2.  No further steps are needed, as `fpcalc.exe` is already in the project folder.\n\n### On Linux (Debian/Ubuntu)\n\n1.  **Install `fpcalc`**: `fpcalc` is usually available in the official repositories.\n    ```bash\n    sudo apt update\n    sudo apt install fpcalc\n    ```\n2.  **Install Python Libraries**:\n    ```bash\n    pip install acoustid mutagen\n    ```\n\n### On Fedora Linux\n\n1.  **Install `fpcalc`**:\n    ```bash\n    sudo dnf install chromaprint-tools\n    ```\n    This package includes the `fpcalc` command-line tool.\n2.  **Install Python Libraries**:\n    ```bash\n    pip install acoustid mutagen\n    ```\n\n---\n\n## Step 3: Configure and Run the Script\n\n1.  **Open `main.py`** in a text editor.\n2.  **Replace the placeholder values** for `ACOUSTID_API_KEY` and `MUSIC_FOLDER` with your own information:\n\n    ```python\n    ACOUSTID_API_KEY = \"YOUR_ACOUSTID_API_KEY\"\n    MUSIC_FOLDER = \"path/to/your/music/folder\"\n    ```\n\n    - Paste the API key you obtained in Step 1.\n    - Specify the path to the folder containing the MP3/WAV files you want to organize.\n\n3.  **Save the file**.\n4.  **Run the script** from your terminal:\n    ```bash\n    python main.py\n    ```\n\nThe script will now go through each music file in your specified folder, identify it, and update its metadata and filename.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Focelotko%2Fclean-tunes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Focelotko%2Fclean-tunes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Focelotko%2Fclean-tunes/lists"}