{"id":29020217,"url":"https://github.com/deezer/skey","last_synced_at":"2025-06-26T01:04:36.454Z","repository":{"id":272310977,"uuid":"916169297","full_name":"deezer/skey","owner":"deezer","description":"Self-supervised key estimation model that matches performance with supervised state-of-the-art model.","archived":false,"fork":false,"pushed_at":"2025-06-06T20:29:28.000Z","size":1162,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-06-06T21:30:46.286Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/deezer.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-01-13T15:32:01.000Z","updated_at":"2025-06-06T20:30:12.000Z","dependencies_parsed_at":null,"dependency_job_id":"428c8c37-9c37-44dc-b345-d31a98520844","html_url":"https://github.com/deezer/skey","commit_stats":null,"previous_names":["deezer/s-key","deezer/skey"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/deezer/skey","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deezer%2Fskey","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deezer%2Fskey/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deezer%2Fskey/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deezer%2Fskey/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deezer","download_url":"https://codeload.github.com/deezer/skey/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deezer%2Fskey/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261978911,"owners_count":23239417,"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":[],"created_at":"2025-06-26T01:04:35.697Z","updated_at":"2025-06-26T01:04:36.395Z","avatar_url":"https://github.com/deezer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# S-KEY\n\n`skey` is a Python package for state-of-the-art automatic **musical key detection** from audio recordings, based on the S-KEY model proposed by Yuexuan Kong et al. The package provides an efficient pipeline for loading audio and inferring musical key using a trained deep learning model ChromaNet. It will be made into a PyPI package soon.\n\n- 📄 [S-KEY: Self-supervised Learning of Major and Minor Keys from Audio](https://arxiv.org/abs/2501.12907)  \n- ✅ Accepted at [ICASSP 2025](https://ieeexplore.ieee.org/xpl/conhome/10887540/proceeding)\n\n## Features\n\n- 🎼 End-to-end musical key detection from raw audio\n- 🧠 A open-sourced pretrained model\n- ⚙️  Simple CLI and Python API\n- 💽 Support for `.wav`, `.mp3`, etc.\n- 🔌 CPU and GPU support\n\n\n## Installation\n\n```bash\npoetry install\n```\n\n## Usage\n\n### 🔧 Command Line Interface (CLI)\n\n```bash\npoetry skey path/to/audio --device cpu\n```\n\nThis will run key detection on the specified audio file or directory using the default model and settings. The prediction will be printed if the path is an audio file, will be saved into a .csv file if the path is a directory.\n\nTo specify additional options, use the following arguments:\n\n```bash\npoetry skey path/to/audio --checkpoint path/to/model.pt --ext mp3 --device cpu\n```\n\n- `--checkpoint`: Path to a custom model checkpoint (`.pt`). If not provided, the default model is used.\n- `--ext`: Audio file extension (default: `wav`), if `path/to/audio` is a directory. Else infers the extension from the file. Supports all formats readable by torchaudio.\n- `--device`: Device to run on (default: `cpu`, e.g., `cuda`, `mps`).\n\n\n**Arguments**:\n\n| Argument                | Description                                               |\n| ----------------------- | --------------------------------------------------------- |\n| `path/to/audio`     | Path to directory with audio files or a single audio file |\n| `--checkpoint`          | Path to model checkpoint (`.pt`). Loads default if not provided. |\n| `--ext`                 | Audio file extension (default: `wav`, supports all formats that can be read by torchaudio) if `path/to/audio` is a directory |\n| `--device`              | Device to run on (default: `cpu`, e.g., `cuda`, `mps`)                  |\n\n\n### 🐍 Python API\n\n```python\nfrom skey import detect_key\n\ndetect_key(\n    audio_dir=\"path/to/audio\",\n    extension=\"mp3\",\n    device=\"cpu\"\n)\n```\n\n**Parameters**:\n\n* `audio_dir` (str): Path to the audio file or directory containing audio files\n* `ckpt_path` (str or None, optional): Path to the model checkpoint file. If `None`, the default model is used.\n* `extension` (str, optional): File extension (default: `\"wav\"`)\n* `device` (str, optional): Device to run on (default: `cpu`)\n\n## 🗂️ Code organization\n\n```\nskey\n├── Dockerfile\n├── LICENSE\n├── Makefile\n├── poetry.lock\n├── pyproject.toml\n├── README.md\n├── skey\n│   ├── __init__.py\n│   ├── chromanet.py\n│   ├── cli.py\n│   ├── convnext.py\n│   ├── hcqt.py\n│   ├── key_detection.py\n│   ├── models\n│   │   └── skey.pt\n├── tests\n│   ├── nocturne_n02_in_e-flat_major.mp3\n│   └── test_detect_key.py\n└── training_utils\n    ├── config\n    │   └── skey.gin\n    ├── skey_loss.py\n    └── skey.py\n\n```\n\n⚠️ The `training_utils/` directory is **not used** in the `skey` package for inference. However, it is **essential** if you plan to **retrain the model**. It contains:\n\n* full model definition\n* loss functions\n* Configuration file (`skey.gin`)\n\nTo retrain, you will need to plug in your own dataloader and training loop using this codebase as a foundation.\n\n## 📚 Reference\n\nIf you use this work in your research, please cite:\n\n```\n@INPROCEEDINGS{kongskey2025,\n  author={Kong, Yuexuan and Meseguer-Brocal, Gabriel and Lostanlen, Vincent and Lagrange, Mathieu and Hennequin, Romain},\n  booktitle={ICASSP 2025 - 2025 IEEE International Conference on Acoustics, Speech and Signal Processing (ICASSP)}, \n  title={S-KEY: Self-supervised Learning of Major and Minor Keys from Audio}, \n  year={2025},\n  pages={1-5},\n  doi={10.1109/ICASSP49660.2025.10890222}}\n```\n\n## 📄 License\n\nThe code of **SKEY** is [MIT-licensed](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeezer%2Fskey","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeezer%2Fskey","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeezer%2Fskey/lists"}