{"id":13891527,"url":"https://github.com/cgzirim/seek-tune","last_synced_at":"2025-07-17T05:31:37.695Z","repository":{"id":226060206,"uuid":"767595043","full_name":"cgzirim/seek-tune","owner":"cgzirim","description":"An implementation of Shazam's song recognition algorithm.","archived":false,"fork":false,"pushed_at":"2025-07-09T14:08:29.000Z","size":60825,"stargazers_count":4785,"open_issues_count":6,"forks_count":524,"subscribers_count":29,"default_branch":"main","last_synced_at":"2025-07-14T21:57:10.263Z","etag":null,"topics":["audio-fingerprinting","audio-processing","go","golang","not-shazam","shazam","song","song-recognition-algorithm"],"latest_commit_sha":null,"homepage":"","language":"Go","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/cgzirim.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}},"created_at":"2024-03-05T15:20:41.000Z","updated_at":"2025-07-14T20:57:48.000Z","dependencies_parsed_at":"2024-03-27T14:30:47.890Z","dependency_job_id":"d8b5477f-4213-47be-a4f4-e1fa407f4aa5","html_url":"https://github.com/cgzirim/seek-tune","commit_stats":null,"previous_names":["cgzirim/song-recognition","cgzirim/not-shazam","cgzirim/seek-sound"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cgzirim/seek-tune","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cgzirim%2Fseek-tune","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cgzirim%2Fseek-tune/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cgzirim%2Fseek-tune/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cgzirim%2Fseek-tune/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cgzirim","download_url":"https://codeload.github.com/cgzirim/seek-tune/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cgzirim%2Fseek-tune/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265568985,"owners_count":23789638,"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","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-fingerprinting","audio-processing","go","golang","not-shazam","shazam","song","song-recognition-algorithm"],"created_at":"2024-08-06T17:00:24.461Z","updated_at":"2025-07-17T05:31:37.685Z","avatar_url":"https://github.com/cgzirim.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eSeekTune :musical_note:\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://drive.google.com/file/d/1I2esH2U4DtXHsNgYbUi4OL-ukV5i_1PI/view\" target=\"_blank\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/e4d01e9c-05cf-4f35-acbc-1e3cd79d1e00\" \n       alt=\"screenshot\" \n       width=\"500\"\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003ca href=\"https://drive.google.com/file/d/1I2esH2U4DtXHsNgYbUi4OL-ukV5i_1PI/view\" target=\"_blank\"\u003eDemo in Video\u003c/a\u003e\u003c/p\u003e\n\n## Description 🎼\nSeekTune is an implementation of Shazam's song recognition algorithm based on insights from these [resources](#resources--card_file_box). It integrates Spotify and YouTube APIs to find and download songs.\n\n[//]: # (## Current Limitations\nWhile the algorithm works excellently in matching a song with its exact file, it doesn't always find the right match from a recording. However, this project is still a work in progress. I'm hopeful about making it work, but I could definitely use some help :slightly_smiling_face:.   \nAdditionally, it currently only supports song files in WAV format.\n)\n\n## Installation :desktop_computer:\n### Prerequisites\n- Golang: [Install Golang](https://golang.org/dl/)\n- FFmpeg: [Install FFmpeg](https://ffmpeg.org/download.html)\n- NPM: To run the client (frontend).\n\n### Steps\n📦 Clone the repository:\n```\ngit clone https://github.com/cgzirim/seek-tune.git\ncd seek-tune\n```\n#### 🐳 Set Up with Docker\nPrerequisites: [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/)\n1. Build and run the application:\n   ```Bash\n   docker-compose up --build\n   ```\n   Visit the app at http://localhost:8080\n2. To stop the application:\n   ```Bash\n   docker-compose down\n   ```\n\n#### 🎧 Spotify API\n\nTo access Spotify metadata, the project now uses the official [Spotify Web API](https://developer.spotify.com/documentation/web-api/). This requires creating a developer application and retrieving a client ID and client secret.\n\nFollow the [official getting started guide](https://developer.spotify.com/documentation/web-api/tutorials/getting-started#request-an-access-token) to:\n\n1. Create a Spotify developer app.\n2. Copy your **Client ID** and **Client Secret**.\n\n##### Setting up Credentials\nInstead of using a credentials.json file, the application now reads these values from environment variables.\n\nCreate a .env file in the server directory  with the following content:\n\n```\nSPOTIFY_CLIENT_ID=your-client-id\nSPOTIFY_CLIENT_SECRET=your-client-secret\n```\n\nMake sure this .env file is loaded into your environment before running the server.\nThe application will automatically read this file to fetch and cache access tokens. If the token is expired or missing, a new one will be requested.\n\n#### 💻 Set Up Natively\nInstall dependencies for the backend\n```\ncd server\ngo get ./...\n```\nInstall dependencies for the client\n```\ncd client\nnpm install\n```\n\n## Usage (Native Setup) :bicyclist:\n\n#### ▸ Start the Client App 🏃‍♀️‍➡️ \n```\n# Assuming you're in the client directory:\n\nnpm start\n```\n#### ▸ Start the Backend App 🏃‍♀️ \nIn a separate terminal window:\n```\ncd server\ngo run *.go serve [-proto \u003chttp|https\u003e (default: http)] [-port \u003cport number\u003e (default: 5000)]\n```\n#### ▸ Download a Song 📥 \nNote: A link from Spotify's mobile app won't work. You can copy the link from either the desktop or web app.\n```\ngo run *.go download \u003chttps://open.spotify.com/.../...\u003e\n```  \n#### ▸ Save local songs to DB (supports all audio formats) 🗃️   \n```\ngo run *.go save [-f|--force] \u003cpath_to_song_file_or_dir_of_songs\u003e\n```\nThe `-f` or `--force` flag allows saving the song even if a YouTube ID is not found. Note that the frontend will not display matches without a YouTube ID.  \n\nNote: if `*.go` does not work try to use `./...` instead.\n  \n#### ▸ Find matches for a song/recording 🔎\n```\ngo run *.go find \u003cpath-to-wav-file\u003e\n```\n#### ▸ Delete fingerprints and songs 🗑️ \n```\ngo run *.go erase\n```\n\n## Example :film_projector:  \nDownload a song \n```\n$ go run *.go download https://open.spotify.com/track/4pqwGuGu34g8KtfN8LDGZm?si=b3180b3d61084018\nGetting track info...\nNow, downloading track...\nFingerprints saved in MongoDB successfully\n'Voilà' by 'André Rieu' was downloaded\nTotal tracks downloaded: 1\n```\n\nFind matches of a song\n```\n$ go run *.go find songs/Voilà\\ -\\ André\\ Rieu.wav\nTop 20 matches:\n        - Voilà by André Rieu, score: 5390686.00\n        - I Am a Child of God by One Voice Children's Choir, score: 2539.00\n        - I Have A Dream by ABBA, score: 2428.00\n        - SOS by ABBA, score: 2327.00\n        - Sweet Dreams (Are Made of This) - Remastered by Eurythmics, score: 2213.00\n        - The Winner Takes It All by ABBA, score: 2094.00\n        - Sleigh Ride by One Voice Children's Choir, score: 2091.00\n        - Believe by Cher, score: 2089.00\n        - Knowing Me, Knowing You by ABBA, score: 1958.00\n        - Gimme! Gimme! Gimme! (A Man After Midnight) by ABBA, score: 1941.00\n        - Take A Chance On Me by ABBA, score: 1932.00\n        - Don't Stop Me Now - Remastered 2011 by Queen, score: 1892.00\n        - I Do, I Do, I Do, I Do, I Do by ABBA, score: 1853.00\n        - Everywhere - 2017 Remaster by Fleetwood Mac, score: 1779.00\n        - You Will Be Found by One Voice Children's Choir, score: 1664.00\n        - J'Imagine by One Voice Children's Choir, score: 1658.00\n        - When You Believe by One Voice Children's Choir, score: 1629.00\n        - When Love Was Born by One Voice Children's Choir, score: 1484.00\n        - Don't Stop Believin' (2022 Remaster) by Journey, score: 1465.00\n        - Lay All Your Love On Me by ABBA, score: 1436.00\n\nSearch took: 856.386557ms\n\nFinal prediction: Voilà by André Rieu , score: 5390686.00\n```\n\n## Database Options 👯‍♀️ \nThis application uses SQLite as the default database, but you can switch to MongoDB if preferred.   \n\n#### Using MongoDB\n1. [Install MongoDB](https://www.mongodb.com/docs/manual/installation/)\n2. Configure MongoDB Connection:  \n   To connect to your MongoDB instance, set the following environment variables:\n\n   * `DB_TYPE`: Set this to \"mongo\" to indicate using MongoDB.\n   * `DB_USER`: The username for your MongoDB database.\n   * `DB_PASS`: The password for your MongoDB database.\n   * `DB_NAME`: The name of the MongoDB database you want to use.\n   * `DB_HOST`: The hostname or IP address of your MongoDB server.\n   * `DB_PORT`: The port number on which your MongoDB server is listening.\n\n   **Note:** The database connection URI is constructed using the environment variables.  \n   If the `DB_USER` or `DB_PASS` environment variables are not set, it defaults to connecting to `mongodb://localhost:27017`.\n\n## Resources  :card_file_box:\n- [How does Shazam work - Coding Geek](https://drive.google.com/file/d/1ahyCTXBAZiuni6RTzHzLoOwwfTRFaU-C/view) (main resource)\n- [Song recognition using audio fingerprinting](https://hajim.rochester.edu/ece/sites/zduan/teaching/ece472/projects/2019/AudioFingerprinting.pdf)\n- [How does Shazam work - Toptal](https://www.toptal.com/algorithms/shazam-it-music-processing-fingerprinting-and-recognition)\n- [Creating Shazam in Java](https://www.royvanrijn.com/blog/2010/06/creating-shazam-in-java/)\n\n\n## Author :black_nib:\n- Chigozirim Igweamaka\n  - Connect with me on [LinkedIn](https://www.linkedin.com/in/ichigozirim/).\n  - Check out my other [GitHub](https://github.com/cgzirim) projects.\n  - Follow me on [Twitter](https://twitter.com/cgzirim).\n \n## License :lock:\nThis project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcgzirim%2Fseek-tune","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcgzirim%2Fseek-tune","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcgzirim%2Fseek-tune/lists"}