{"id":21626226,"url":"https://github.com/adamjakab/beetspluginxtractor","last_synced_at":"2025-07-03T06:02:26.996Z","repository":{"id":43409647,"uuid":"246947677","full_name":"adamjakab/BeetsPluginXtractor","owner":"adamjakab","description":"A beets plugin for obsessive-compulsive music geeks to add low and high level musical information to their songs.","archived":false,"fork":false,"pushed_at":"2024-05-26T20:01:18.000Z","size":30488,"stargazers_count":50,"open_issues_count":7,"forks_count":5,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-06-14T01:51:34.450Z","etag":null,"topics":["beets","beets-plugin","music","music-analysis"],"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/adamjakab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2020-03-12T23:18:32.000Z","updated_at":"2025-06-09T21:07:23.000Z","dependencies_parsed_at":"2024-11-25T01:12:47.050Z","dependency_job_id":"c20cdc4c-08fd-4c72-af9e-d22cee0a92c2","html_url":"https://github.com/adamjakab/BeetsPluginXtractor","commit_stats":{"total_commits":57,"total_committers":4,"mean_commits":14.25,"dds":"0.38596491228070173","last_synced_commit":"a52e9512c8bb16528d0d17e81f162cdc94930512"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/adamjakab/BeetsPluginXtractor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamjakab%2FBeetsPluginXtractor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamjakab%2FBeetsPluginXtractor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamjakab%2FBeetsPluginXtractor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamjakab%2FBeetsPluginXtractor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adamjakab","download_url":"https://codeload.github.com/adamjakab/BeetsPluginXtractor/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamjakab%2FBeetsPluginXtractor/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263271487,"owners_count":23440395,"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":["beets","beets-plugin","music","music-analysis"],"created_at":"2024-11-25T01:12:36.290Z","updated_at":"2025-07-03T06:02:26.953Z","avatar_url":"https://github.com/adamjakab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Test \u0026 Release \u0026 Deploy](https://github.com/adamjakab/BeetsPluginXtractor/actions/workflows/test_release_deploy.yml/badge.svg)](https://github.com/adamjakab/BeetsPluginXtractor/actions/workflows/test_release_deploy.yml)\n[![Coverage Status](https://coveralls.io/repos/github/adamjakab/BeetsPluginXtractor/badge.svg?branch=master)](https://coveralls.io/github/adamjakab/BeetsPluginXtractor?branch=master)\n[![PyPi](https://img.shields.io/pypi/v/beets-xtractor.svg)](https://pypi.org/project/beets-xtractor/)\n[![PyPI pyversions](https://img.shields.io/pypi/pyversions/beets-xtractor.svg)](https://pypi.org/project/beets-xtractor/)\n[![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.txt)\n\n# Xtractor (Beets Plugin)\n\nThe _beets-xtractor_ plugin lets you, through the use of the [Essentia](https://essentia.upf.edu/index.html) extractors,\nto obtain low and high level musical information from your songs.\n\nCurrently, the following attributes are extracted for each library item:\n`bpm`, `danceability`, `beats_count`, `average_loudness`, `danceable`, `gender`, `is_male`, `is_female`,\n`genre_rosamerica`, `voice_instrumental`, `is_voice`, `is_instrumental`, `mood_acoustic`,\n`mood_aggressive`, `mood_electronic`, `mood_happy`, `mood_sad`, `mood_party`, `mood_relaxed`, `mood_mirex`,\n`mood_mirex_cluster_1`, `mood_mirex_cluster_2`, `mood_mirex_cluster_3`, `mood_mirex_cluster_4`, `mood_mirex_cluster_5`\n\n## Installation\n\nThe plugin can be installed via:\n\n```shell script\npip install beets-xtractor\n```\n\nand activated the usual way by adding `xtractor` to the list of plugins in your configuration:\n\n```yaml\nplugins:\n  - xtractor\n```\n\n### Install the Essentia extractors\n\nYou will also need the `streaming_extractor_music` binary extractor from the [Essentia project](#credits).\nPlease refer to the [official installation documentation](https://essentia.upf.edu/installing.html#compiling-essentia-from-source)\nfor the installation procedure for your OS. If you are stuck you can use\nthe [Issue tracker](https://github.com/adamjakab/BeetsPluginXtractor/issues). If you are compiling Essentia from source,\nmake sure you compile it with Gaia support (`--with-gaia`) otherwise will not be able to use the high level models.\n\n### Download the SVM models\n\nFor computing the high-level descriptors you will need the prebuilt trained models for prediction. You need to download these from\nhere: [SVM Models](https://essentia.upf.edu/svm_models/). I suggest that you download the most recent beta5 version.\nThis means that your binaries must match this version. Put the downloaded models in any folder from which they can be\naccessed.\n\n## Configuration\n\nAll your configuration will need to go under the `xtractor` key. This is what your configuration should look like:\n\n```yaml\nxtractor:\n  auto: no\n  dry-run: no\n  write: yes\n  threads: 1\n  force: no\n  quiet: no\n  keep_output: yes\n  keep_profiles: no\n  output_path: /mnt/data/xtraction_data\n  essentia_extractor: /mnt/data/extractors/beta5/streaming_extractor_music\n  extractor_profile:\n    highlevel:\n      svm_models:\n        - /mnt/data/extractors/beta5/svm_models/danceability.history\n        - /mnt/data/extractors/beta5/svm_models/gender.history\n        - /mnt/data/extractors/beta5/svm_models/genre_rosamerica.history\n        - /mnt/data/extractors/beta5/svm_models/mood_acoustic.history\n        - /mnt/data/extractors/beta5/svm_models/mood_aggressive.history\n        - /mnt/data/extractors/beta5/svm_models/mood_electronic.history\n        - /mnt/data/extractors/beta5/svm_models/mood_happy.history\n        - /mnt/data/extractors/beta5/svm_models/mood_sad.history\n        - /mnt/data/extractors/beta5/svm_models/mood_party.history\n        - /mnt/data/extractors/beta5/svm_models/mood_relaxed.history\n        - /mnt/data/extractors/beta5/svm_models/voice_instrumental.history\n        - /mnt/data/extractors/beta5/svm_models/moods_mirex.history\n```\n\nFirst of all, you will need adjust all paths. Put the path of the extractor binary in `essentia_extractor` and\nsubstitute the location of the SVM models with your local path under the `svm_models` section. Finally, set\nthe `output_path` to indicate where the extracted data files will be stored. If you do not set this, a temporary path\nwill be used.\nwill be used.\n\n**Note on shell tilde expansion**: Please note that you cannot use shell expansion on the `svm_models` (i.e.: do not use `~` for your home folder).\nThe entire section of `extractor_profile` is passed as-is to the essentia extractor binary and it will not do tilde expansion on your paths.\nThe rest of the path keys such as `essentia_extractor` and `output_path` are used by the plugin itself and it will take\ncare of expanding the tilde symbol (`~`) to the home directory of the user running the script.\ncare of expanding the tilde symbol (`~`) to the home directory of the user running the script.\n\nBy default both `keep_output` and `keep_profile` options are set to `no`. This means that after extraction (and the\nstorage of the important information) the profile files used to pass to the extractors, and the json files created by\nthe extractors will be deleted. There are various reasons you might want to keep these files. One is for debugging\npurposes. Another is to see what else is in these files (there is a lot) and maybe to use them with some other projects\nof yours. Lastly, you might want to keep these because the plugin only extracts data if these files are not present. If\nyou store them, on a successive extraction, the plugin will skip the extraction and use these files (they are named\nby `mb_trackid`) - speeding up the process a lot.\n\nThe `force` option instructs the plugin to execute on items which already have the required properties.\n\nThe `threads` option sets the number of concurrent executions. By default this is set to 1.\nIf you remove this option or if you set it to 0 the number of CPU cores present on your machine will be used.\nThe extraction is quite a CPU intensive process so there might be cases when you want to limit it to just 1.\n\nThe `write` option instructs the plugin to write the extracted attributes to the media file right away. Note that only `bpm` is actually written to the media file, all the other attributes are flex attributes and are only stored in the database.\n\nThe `dry-run` option shows what would be done without actually doing it.\n\n**NOTE**: Please note that the `auto` option is not yet implemented. For now you will have to call the xtractor plugin manually.\n\n## Usage\n\nInvoke the plugin as:\n\n    $ beet xtractor [options] [QUERY...]\n\nFor a more verbose reporting use the `-v` flag on `beet`:\n\n    $ beet -v xtractor [options] [QUERY...]\n\nThe plugin has also got a shorthand `xt` so you can also invoke it like this:\n\n    $ beet xt [options] [QUERY...]\n\nThe following command line options are available:\n\n**--dry-run [-d]**: Only show what would be done - displays the extracted values but does not store them in the library.\n\n**--write [-w]**: Write the values (bpm only) to the media files.\n\n**--threads=THREADS [-t THREADS]**: The number of concurrently running executions.\n\n**--force [-f]**: Force the analysis of all items (skip attribute checks).\n\n**--count-only [-c]**: Show the number of items to be processed and exit. Extraction will not be executed.\n\n**--quiet [-q]**: Run without any output.\n\n**--version [-v]**: Display the version number of the plugin. Useful when you need to report some issue and you have to state the version of the plugin you are using.\n\nThese command line options will override those specified in the configuration file.\n\n## Issues\n\n- If something is not working as expected please use the Issue tracker.\n- If the documentation is not clear please use the Issue tracker.\n- If you have a feature request please use the Issue tracker.\n- In any other situation please use the Issue tracker.\n\n## Other plugins by the same author\n\n- [beets-goingrunning](https://github.com/adamjakab/BeetsPluginGoingRunning)\n- [beets-xtractor](https://github.com/adamjakab/BeetsPluginXtractor)\n- [beets-yearfixer](https://github.com/adamjakab/BeetsPluginYearFixer)\n- [beets-autofix](https://github.com/adamjakab/BeetsPluginAutofix)\n- [beets-describe](https://github.com/adamjakab/BeetsPluginDescribe)\n- [beets-bpmanalyser](https://github.com/adamjakab/BeetsPluginBpmAnalyser)\n- [beets-template](https://github.com/adamjakab/BeetsPluginTemplate)\n\n## Credits\n\nEssentia is an open-source C++ library with Python bindings for audio analysis and audio-based music information retrieval. It is released under the Affero GPLv3 license and is also available under proprietary license upon request. This plugin is just a mere wrapper around this library. [Learn more about the Essentia project](http://essentia.upf.edu)\n\n## References\n\n- [Essentia](https://essentia.upf.edu/index.html)\n- [SVM Models](https://essentia.upf.edu/svm_models/)\n- [Essentia Licensing](https://essentia.upf.edu/licensing_information.html)\n- [MTG Github - Music Technology Group](https://github.com/MTG)\n- [Acousticbrainz Downloads](https://acousticbrainz.org/download)\n\n## Final Remarks\n\nEnjoy!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadamjakab%2Fbeetspluginxtractor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadamjakab%2Fbeetspluginxtractor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadamjakab%2Fbeetspluginxtractor/lists"}