{"id":17681277,"url":"https://github.com/madeindjs/music-metadata-search","last_synced_at":"2026-02-25T12:31:37.822Z","repository":{"id":237563721,"uuid":"794756252","full_name":"madeindjs/music-metadata-search","owner":"madeindjs","description":"Search in your local music library using quick filter on metadata tags","archived":false,"fork":false,"pushed_at":"2025-01-12T22:34:32.000Z","size":132,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-13T09:17:35.381Z","etag":null,"topics":["audio","cli","flac","metadata","mp3","nodejs","ogg"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/madeindjs.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}},"created_at":"2024-05-01T22:10:48.000Z","updated_at":"2025-01-12T22:34:35.000Z","dependencies_parsed_at":"2024-12-27T22:57:12.106Z","dependency_job_id":null,"html_url":"https://github.com/madeindjs/music-metadata-search","commit_stats":null,"previous_names":["madeindjs/music-finder","madeindjs/music-metadata-search"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madeindjs%2Fmusic-metadata-search","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madeindjs%2Fmusic-metadata-search/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madeindjs%2Fmusic-metadata-search/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madeindjs%2Fmusic-metadata-search/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/madeindjs","download_url":"https://codeload.github.com/madeindjs/music-metadata-search/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241100992,"owners_count":19909821,"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","cli","flac","metadata","mp3","nodejs","ogg"],"created_at":"2024-10-24T09:10:42.488Z","updated_at":"2026-02-25T12:31:37.815Z","avatar_url":"https://github.com/madeindjs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Music Metadata Search\n\n[![npm version](https://badge.fury.io/js/music-metadata-search.svg)](https://badge.fury.io/js/music-metadata-search)\n[![jsr version](https://jsr-badge.deno.dev/@madeindjs/music-metadata-search/stable.svg)](https://jsr.io/@madeindjs/music-metadata-search)\n\nSearch in your local music library using quick filter on metadata tags.\n\nMy main usage is to find musics I want to play and pipe it to [mpv](https://mpv.io/) but it can be used for different purposes (see \"usage\").\n\n```sh\nmusic-metadata-search ~/music --where \"genre like '%sport%'\" | mpv --playlist=-\n```\n\nIt will:\n\n- walk in the given directory and parse metadata using [`music-metadata`](https://github.com/borewit/music-metadata)\n- filter results\n- pipe results\n\nMy main objective is to have a CLI tool fast \u0026 convenient, for myself. It takes 5s for my library of 150go (5406 files), and then less than 1s using the cache.\n\n## Install\n\n```sh\nnpm i music-metadata-search\n```\n\n## CLI usage\n\nGenerate list of file path matching where the genre contains \"French\":\n\n```sh\nmusic-metadata-search ~/music/ -g 'French'\n```\n\nOr you can pipe to [mpv](https://mpv.io/) to play them. Example playlist my new Rock songs:\n\n```sh\nmusic-metadata-search ~/music/ -g 'rock' | mpv --playlist=-\n```\n\nOr you can export an old school French Touch playlist as `.m3u` file:\n\n```sh\nmusic-metadata-search ~/music/ -g 'French' --year '2000..2005' -f m3u \u003e french-touch.m3u\n```\n\nOr getting the \"Daft Punks albums before 2000\" using JSON output and [jq](https://jqlang.github.io/jq/)\n\n```sh\nmusic-metadata-search ~/music/ -a 'daft' --year '\u003c2000' -f json | jq '[.[].album] | unique'\n```\n\nUse `music-metadata-search --help` for more information.\n\n```\nUsage: music-metadata-search [options] [path]\n\nSearch in your local music library using quick filters on metadata tags\n\nArguments:\n  path                                               The directory of local files (default: \"/home/alexandre/github/madeindjs/music-metadata-search\")\n\nOptions:\n  -V, --version                                      output the version number\n  -q, --query [genre]                                Search the term everywhere)\n  -g, --genre [genre]                                Filter by genre of the track using `LIKE` operator\n  -a, --artist [artist]                              Filter by artist of the track using `LIKE` operator\n  -b, --album [album]                                Filter by album of the track using `LIKE` operator\n  -y, --year [year]                                  Filter by year of the track\n                                                     If a single value is provided, it will filter by `=`, you can also give a range like `1..10 to filter using `BETWEEN` operator\n  -t, --title [title]                                Title of the track to search using `LIKE` operator\n  -c, --comment [comment]                            Comment of the track to search using `LIKE` operator\n  -d,--duration [duration]                           Filter by duration of the track (in seconds)\n                                                     If a single value is provided, it will filter by `=`, you can also give a range like `1..10 to filter using `BETWEEN` operator\n  --bpm [bpm]                                        Filter by BPM of the track\n                                                     If a single value is provided, it will filter by `=`, you can also give a range like `1..10 to filter using `BETWEEN` operator\n  --bitrate [bitrate]                                Filter by bitrate of the track (in bits/seconds)\n                                                     If a single value is provided, it will filter by `=`, you can also give a range like `1..10 to filter using `BETWEEN` operator\n  --musicbrainzTrackId [musicbrainzTrackId]\n  --musicbrainzArtistId [musicbrainzArtistId]\n  --musicbrainzAlbumId [musicbrainzAlbumId]\n  --musicbrainzRecordingId [musicbrainzRecordingId]\n  -l, --limit [limit]                                Limit the number of tracks returned\n  -f, --format [format]                              Output format (choices: \"txt\", \"json\", \"m3u\", default: \"txt\")\n  --ext [ext...]                                     Extensions of Audio files to scan (default: [\".mp3\",\".flac\",\".m4a\",\".ogg\",\".aac\"])\n  --log-level [logLevel]                             Log level (choices: \"trace\", \"debug\", \"info\", \"warn\", \"error\", \"fatal\", default: \"fatal\")\n  -h, --help                                         display help for command\n```\n\n## Lib usage\n\n```js\nimport { search } from \"music-metadata-search\";\n\nconst tracks = search(\"/home/alexandre/Musique/\", {\n  // Filter artist of the track using `LIKE` operator\n  artist: \"Daft\",\n  // Extensions of Audio files to scan\n  ext: [\".flac\"],\n  // Log level for [pino](https://www.npmjs.com/package/pino) (default to `'silent'`)\n  logLevel: \"debug\",\n  // Filter by title of the track to search using `LIKE` operator\n  title: \"One\",\n  // Limit the number of tracks returned\n  limit: 10,\n});\nfor await (const track of tracks) console.log(track);\n\n/*\n  {\n    path: '/home/alexandre/Musique/Daft Punk/2007-12-04 -  Alive 2007/08 One More Time _ Aerodynamic.flac',\n    title: 'One More Time / Aerodynamic',\n    genre: 'Electronic',\n    artist: 'Daft Punk',\n    album: 'Alive 2007',\n    year: 2007\n  }\n  {\n    path: '/home/alexandre/Musique/Daft Punk/2001-03-13 -  Discovery/01 One More Time.flac',\n    title: 'One More Time',\n    genre: 'House',\n    artist: 'Daft Punk',\n    album: 'Discovery',\n    year: 2001\n  }\n*/\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadeindjs%2Fmusic-metadata-search","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmadeindjs%2Fmusic-metadata-search","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadeindjs%2Fmusic-metadata-search/lists"}