Metadata-Version: 2.4
Name: tagdetector
Version: 0.0.1
Summary: Parse inconsistent song metadata into more structured and predictable data using an LLM. Mainly intended for SoundCloud.
Author: Allinen
Author-email: Allinen <151441334+Allinen@users.noreply.github.com>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Dist: requests
Requires-Dist: pydantic
Requires-Python: >=3.9
Project-URL: Homepage, https://github.com/Allinen/TagDetector
Project-URL: Repository, https://github.com/Allinen/TagDetector
Project-URL: Issues, https://github.com/Allinen/TagDetector/issues
Description-Content-Type: text/markdown


# TagDetector

TagDetector uses an LLM to parse inconsistent tags to a more predictable format. This is mostly intended for SoundCloud, but can be easily adapted to work with anything. Currently only supports producers and features, feel free to contribute to add more features based on your use cases.
## Installation

Install TagDetecter like so:

```bash
pip install tagdetector
```
You will also need Ollama running at `http://localhost:11434` with the model `qwen2.5:7b-instruct` available. You can use anything else, those are just the default values.
## Usage/Examples

```python
from tagdetector.llm_extract import parse_track

parse_track(
    SourceTrack.from_raw_soundcloud_song_data("Real Artist Name", raw_song_data)
)
```
In the above example we are creating a `SourceTrack` with a predefined function that reads it from `raw_song_data`. It is data from the SoundCloud API (works with the most recent format, your mileage may vary if you use older sources). 

If you wish to use something other than SoundCloud data or prefer to create it manually, you could do

```python
SourceTrack(
    raw_title: "Song w/ my friend",
    real_artist_name="Real Artist Name",
    display_artist_name="Real Artiast Name!!!",
    extra_data: {"description": "My cool song"},
)
```

So what is `real_artist_name`? It is defined by the user as whatever they feel is the "correct" name for the artist that the parser should respect. This is useful for cases where the artist namedrops themselves in the title, in which case it will correctly strip that, but not mark it as a feature/producer. I haven't experimented yet with putting multiple artist names in there for aliases for better detection, but I imagine the changes required for that would be trivial. 

In the context of soundcloud, `display_artist_name` can include features or otherwise stylized versions of the artist name and is treated as such. Use it as you seek fit.
## Contributing

Pull requests welcome, you can also open issues for specific examples where parsing was incorrect.

Note: It is completely impossible parse every track correctly and it is unrealistic to expect that, as artists sometimes really do not care about the legibility of their titles (worst offenders include, but are not limited to, listing features in the middle of song titles...)
## License

[GPL-3.0](https://choosealicense.com/licenses/gpl-3.0/)