# Yumee
**Embed metadata into your music files, whatever the type**
Yumee stands for *Yet Unother MEtadata Embedder*
## Features
- Automatic type detection based on the file extension
- Currently supported : MP3, M4A, FLAC, OGG (Vorbis), OPUS
- Detection of badly formatted files
- Easy to use, straightforward interface
- Possible to use via DI integration
## Installation
### Pip
```
pip install yumee
```
### Poetry
[Poetry](https://python-poetry.org/) is a Python dependency management and packaging tool. I actually use it for this project.
```
poetry add yumee
```
## Usage
There are 2 ways to use this library : using the SongMetadataEmbedder object or via the DI.
### Using SongMetadataEmbedder
The library exposes the SongMetadataEmbedder class. This class has 1 method : `open_file`.
`open_file` opens an audio file at a provided path and returns a `BaseSongFile` to manipulate its metadata.
Once you have a `BaseSongFile`, you have access to methods like `embed` or `extract`. `embed` modifies the metadata of the SongFile according to the data provided. `extract` returns the metadata that was embedded in the file.
**Example 1 :**
```python
from pathlib import Path
from yumee import SongMetadataEmbedder
embedder = SongMetadataEmbedder()
path = Path("path/to/file.mp3")
with embedder.open_file(path) as song_file:
song_file.title = "New Title"
```
*It is recommended to use 'open_file' with the 'with' statement as it will ensure that the modifications are saved as you exit the block. Otherwise, you have to make sure to call 'save' to save the modifications.*
**Example 2 :**
```python
from pathlib import Path
from yumee import SongMetadataEmbedder, SongMetadata
embedder = SongMetadataEmbedder()
path = Path("path/to/file.mp3")
metadata = SongMetadata(title="New Title")
song_file = embedder.open_file(path)
song_file.embed(metadata)
```
*The 'embed' method automatically saves the modifications done. This is why I don't use 'open_file' with a 'with' statement.*
### Using DI
The library also exposes a `BaseSongFileProvider` interface and a `add_yumee` function for [Taipan-DI](https://github.com/Billuc/Taipan-DI).
In this function, SongFileProviders are registered as a Pipeline. Each SongFileProvider correspond to a specific file type and generates a `BaseSongFile`. Resolve the pipeline and execute it to have a `BaseSongFile` you can then manipulate.
**Example :**
```python
from yumee import BaseSongFileProvider, add_yumee
from taipan_di import DependencyCollection
services = DependencyCollection()
add_yumee(services)
provider = services.build()
song_file_provider = provider.resolve(BaseSongFileProvider)
path = Path("path/to/file.mp3")
with song_file_provider.exec(path) as song_file:
...
```
## Inspirations
This library is partially inspired by spotDL's [spotify-downloader](https://github.com/spotDL/spotify-downloader) and utilises [mutagen](https://mutagen.readthedocs.io/en/latest/).
## TODO
This library isn't stable yet and a lot of things can still be improved.
If there is something you want to see added or if something does not work as you want it to, feel free to open an issue.
Here is a list of features I have in mind and will be working on :
- ~~Generate SongMetadata from a SongFile~~
- Support Wav
- ISRC tag
- MP3 separator support
- Popularity tag (ID3)
Raw data
{
"_id": null,
"home_page": "https://github.com/Billuc/Yumee",
"name": "yumee",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "yumee,song metadata,song,metadata,metadata embedder,python,mp3,m4a,ogg,flac,opus",
"author": "Billuc",
"author_email": "billuc@hotmail.fr",
"download_url": "https://files.pythonhosted.org/packages/97/8d/fb02c2d3a545b9ab2feee2b18236e3b19f84530187563e3e520eed356374/yumee-0.0.3.tar.gz",
"platform": null,
"description": "# Yumee\n\n**Embed metadata into your music files, whatever the type** \nYumee stands for *Yet Unother MEtadata Embedder*\n\n## Features\n\n- Automatic type detection based on the file extension\n - Currently supported : MP3, M4A, FLAC, OGG (Vorbis), OPUS\n- Detection of badly formatted files\n- Easy to use, straightforward interface\n- Possible to use via DI integration\n\n## Installation\n\n### Pip\n\n```\npip install yumee\n```\n\n### Poetry\n\n[Poetry](https://python-poetry.org/) is a Python dependency management and packaging tool. I actually use it for this project.\n\n```\npoetry add yumee\n```\n\n## Usage\n\nThere are 2 ways to use this library : using the SongMetadataEmbedder object or via the DI.\n\n### Using SongMetadataEmbedder\n\nThe library exposes the SongMetadataEmbedder class. This class has 1 method : `open_file`.\n\n`open_file` opens an audio file at a provided path and returns a `BaseSongFile` to manipulate its metadata. \nOnce you have a `BaseSongFile`, you have access to methods like `embed` or `extract`. `embed` modifies the metadata of the SongFile according to the data provided. `extract` returns the metadata that was embedded in the file.\n\n**Example 1 :**\n\n```python\nfrom pathlib import Path\nfrom yumee import SongMetadataEmbedder\n\nembedder = SongMetadataEmbedder()\npath = Path(\"path/to/file.mp3\")\n\nwith embedder.open_file(path) as song_file:\n song_file.title = \"New Title\"\n```\n\n*It is recommended to use 'open_file' with the 'with' statement as it will ensure that the modifications are saved as you exit the block. Otherwise, you have to make sure to call 'save' to save the modifications.*\n\n**Example 2 :**\n\n```python\nfrom pathlib import Path\nfrom yumee import SongMetadataEmbedder, SongMetadata\n\nembedder = SongMetadataEmbedder()\npath = Path(\"path/to/file.mp3\")\nmetadata = SongMetadata(title=\"New Title\")\n\nsong_file = embedder.open_file(path)\nsong_file.embed(metadata)\n```\n\n*The 'embed' method automatically saves the modifications done. This is why I don't use 'open_file' with a 'with' statement.*\n\n### Using DI\n\nThe library also exposes a `BaseSongFileProvider` interface and a `add_yumee` function for [Taipan-DI](https://github.com/Billuc/Taipan-DI).\n\nIn this function, SongFileProviders are registered as a Pipeline. Each SongFileProvider correspond to a specific file type and generates a `BaseSongFile`. Resolve the pipeline and execute it to have a `BaseSongFile` you can then manipulate.\n\n**Example :**\n\n```python\nfrom yumee import BaseSongFileProvider, add_yumee\nfrom taipan_di import DependencyCollection\n\nservices = DependencyCollection()\nadd_yumee(services)\nprovider = services.build()\n\nsong_file_provider = provider.resolve(BaseSongFileProvider)\npath = Path(\"path/to/file.mp3\")\n\nwith song_file_provider.exec(path) as song_file:\n ...\n```\n\n## Inspirations\n\nThis library is partially inspired by spotDL's [spotify-downloader](https://github.com/spotDL/spotify-downloader) and utilises [mutagen](https://mutagen.readthedocs.io/en/latest/).\n\n## TODO\n\nThis library isn't stable yet and a lot of things can still be improved.\nIf there is something you want to see added or if something does not work as you want it to, feel free to open an issue.\n\nHere is a list of features I have in mind and will be working on :\n\n- ~~Generate SongMetadata from a SongFile~~\n- Support Wav\n- ISRC tag\n- MP3 separator support\n- Popularity tag (ID3)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Yet Unother MEtadata Embedder",
"version": "0.0.3",
"project_urls": {
"Documentation": "https://github.com/Billuc/Yumee",
"Homepage": "https://github.com/Billuc/Yumee",
"Repository": "https://github.com/Billuc/Yumee"
},
"split_keywords": [
"yumee",
"song metadata",
"song",
"metadata",
"metadata embedder",
"python",
"mp3",
"m4a",
"ogg",
"flac",
"opus"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "253468893bff8f2c19ca71d57fe8de47db4a2cd2f53c4655f9542bab6ed8132b",
"md5": "e87539879908c1707aabc72bf7aaea49",
"sha256": "a54910cc13844a26cab75b99d8138702b67eeeb40d24e902059c695b7774bc57"
},
"downloads": -1,
"filename": "yumee-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e87539879908c1707aabc72bf7aaea49",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 22714,
"upload_time": "2023-07-18T13:40:50",
"upload_time_iso_8601": "2023-07-18T13:40:50.445494Z",
"url": "https://files.pythonhosted.org/packages/25/34/68893bff8f2c19ca71d57fe8de47db4a2cd2f53c4655f9542bab6ed8132b/yumee-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "978dfb02c2d3a545b9ab2feee2b18236e3b19f84530187563e3e520eed356374",
"md5": "2584189c74180c95ec61df826b61f8be",
"sha256": "3f5bda58daccabc89181a625ed6122db47abcdde099ac5a0c402521d73d3db4b"
},
"downloads": -1,
"filename": "yumee-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "2584189c74180c95ec61df826b61f8be",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 12831,
"upload_time": "2023-07-18T13:40:51",
"upload_time_iso_8601": "2023-07-18T13:40:51.509228Z",
"url": "https://files.pythonhosted.org/packages/97/8d/fb02c2d3a545b9ab2feee2b18236e3b19f84530187563e3e520eed356374/yumee-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-18 13:40:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Billuc",
"github_project": "Yumee",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "yumee"
}
JSON
