music-kraken-core/README.md

270 lines
6.5 KiB
Markdown
Raw Permalink Normal View History

2023-06-23 11:31:49 +00:00
# Music Kraken
2023-02-22 17:56:28 +00:00
2024-04-16 17:09:10 +00:00
[![Woodpecker CI Status](https://ci.elara.ws/api/badges/59/status.svg)](https://ci.elara.ws/repos/59)
2023-06-12 19:53:40 +00:00
<img src="assets/logo.svg" width=300 alt="music kraken logo"/>
- [Music Kraken](#music-kraken)
- [Installation](#installation)
- [From source](#from-source)
- [Notes for WSL](#notes-for-wsl)
- [Quick-Guide](#quick-guide)
2024-04-10 12:09:13 +00:00
- [Query](#query)
- [CONTRIBUTE](#contribute)
- [Matrix Space](#matrix-space)
2023-06-23 11:31:49 +00:00
- [TODO till the next release](#todo-till-the-next-release)
- [Programming Interface / Use as Library](#programming-interface--use-as-library)
- [Quick Overview](#quick-overview)
- [Data Model](#data-model)
- [Data Objects](#data-objects)
- [Creation](#creation)
2023-02-06 08:44:11 +00:00
2023-02-22 17:56:28 +00:00
---
2022-11-15 16:01:17 +00:00
2022-11-15 09:52:54 +00:00
## Installation
You can find and get this project from either [PyPI](https://pypi.org/project/music-kraken/) as a Python-Package,
or simply the source code from [GitHub](https://github.com/HeIIow2/music-downloader). Note that even though
everything **SHOULD** work cross-platform, I have only tested it on Ubuntu.
If you enjoy this project, feel free to give it a star on GitHub.
2022-11-15 09:52:54 +00:00
2024-01-13 16:20:16 +00:00
> THE PyPI PACKAGE IS OUTDATED
### From source
if you use Debian or Ubuntu:
2022-11-15 09:52:54 +00:00
```sh
2024-01-13 16:20:16 +00:00
git clone https://github.com/HeIIow2/music-downloader
sudo apt install pandoc
2022-11-15 09:52:54 +00:00
2024-01-13 16:20:16 +00:00
cd music-downloader/
python3 -m pip install -r requirements.txt
2022-11-15 09:52:54 +00:00
```
2024-01-13 16:20:16 +00:00
then you can add to `~/.bashrc`
```
alias music-kraken='cd your/directory/music-downloader/src; python3 -m music_kraken'
alias 🥺='sudo'
```
```sh
source ~/.bashrc
music-kraken
```
2022-11-23 19:07:31 +00:00
### Notes for WSL
2022-11-23 19:12:38 +00:00
If you choose to run it in WSL, make sure ` ~/.local/bin` is added to your `$PATH` [#2][i2]
2022-11-23 19:07:31 +00:00
2022-11-15 09:52:54 +00:00
## Quick-Guide
2024-04-10 12:09:13 +00:00
The **Genre** you define at the start, is the folder my program will download the files into, as well as the value of the ID3 genre field.
2022-11-15 09:52:54 +00:00
2023-06-12 19:53:40 +00:00
When it drops you into the **shell** 2 main things are important:
1. You search with `s: <query/url>`
2. You choose an option with just the index number of the option
2024-04-10 12:09:13 +00:00
3. You download with `d: <options/url>`, where the options are comma separated
2023-06-12 19:53:40 +00:00
### Query
2024-04-10 12:09:13 +00:00
The syntax for the query is really simple.
2022-11-15 09:52:54 +00:00
2024-04-10 12:09:13 +00:00
```mk
2023-06-23 11:31:49 +00:00
> s: #a <any artist>
2022-11-23 07:37:56 +00:00
searches for the artist <any artist>
2022-11-15 09:52:54 +00:00
2024-04-10 12:09:13 +00:00
> s: #a <any artist> #r <any release>
2022-11-23 07:37:56 +00:00
searches for the release (album) <any release> by the artist <any artist>
2022-11-15 09:52:54 +00:00
2023-06-23 11:31:49 +00:00
> s: #r <any release> Me #t <any track>
2022-11-23 07:37:56 +00:00
searches for the track <any track> from the release <any relaese>
2022-11-15 09:52:54 +00:00
```
2024-04-10 12:09:13 +00:00
The escape character is as usual `\`.
2022-10-14 13:23:47 +00:00
---
2023-02-22 17:56:28 +00:00
## CONTRIBUTE
I am happy about every pull request. To contribute look [here](contribute.md).
2023-06-23 11:31:49 +00:00
## Matrix Space
2023-02-22 17:56:28 +00:00
2024-04-10 12:09:13 +00:00
<img align="right" alt="music-kraken logo" src="assets/element_logo.png" width=100>
2023-02-22 17:56:28 +00:00
2024-04-10 12:09:13 +00:00
I decided against creating a discord server, due to various communities get often banned from discord. A good and free Alternative are Matrix Spaces. I recommend the use of the Client [Element](https://element.io/download). It is completely open source.
2023-02-22 17:56:28 +00:00
2024-04-10 12:09:13 +00:00
**Click [this invitation](https://matrix.to/#/#music-kraken:matrix.org) _([https://matrix.to/#/#music-kraken:matrix.org](https://matrix.to/#/#music-kraken:matrix.org))_ to join.**
2023-02-22 17:56:28 +00:00
2023-06-23 11:31:49 +00:00
## TODO till the next release
> These Points will most likely be in the changelogs.
2024-04-10 12:09:13 +00:00
- [x] Migrate away from pandoc, to a more lightweight alternative, that can be installed over PiPY.
2023-06-23 11:31:49 +00:00
- [ ] Update the Documentation of the internal structure. _(could be pushed back one release)_
2023-02-22 17:56:28 +00:00
---
2023-02-07 11:00:54 +00:00
# Programming Interface / Use as Library
2023-06-23 11:31:49 +00:00
This application is $100\%$ centered around Data. Thus, the most important thing for working with musik kraken is, to understand how I structured the data.
2023-02-27 13:29:09 +00:00
2023-03-13 12:59:15 +00:00
## Quick Overview
2023-02-27 13:29:09 +00:00
- explanation of the [Data Model](#data-model)
- how to use the [Data Objects](#data-objects)
2024-04-10 12:09:13 +00:00
- further Dokumentation of _hopefully_ [most relevant classes](documentation/objects.md)
- the [old implementation](documentation/old_implementation.md)
2023-01-23 15:57:00 +00:00
2023-02-07 11:00:54 +00:00
```mermaid
2023-02-27 13:29:09 +00:00
---
2023-06-23 11:31:49 +00:00
title: Quick Overview (outdated)
2023-02-27 13:29:09 +00:00
---
2023-02-07 11:00:54 +00:00
sequenceDiagram
participant pg as Page (eg. YouTube, MB, Musify, ...)
participant obj as DataObjects (eg. Song, Artist, ...)
participant db as DataBase
obj ->> db: write
db ->> obj: read
pg -> obj: find a source for any page, for object.
obj -> pg: add more detailed data from according page.
obj -> pg: if available download audio to target.
```
2023-02-27 13:29:09 +00:00
## Data Model
2023-02-27 13:21:19 +00:00
The Data Structure, that the whole programm is built on looks as follows:
```mermaid
---
title: Music Data
---
erDiagram
2023-02-27 13:23:56 +00:00
Target {
}
Lyrics {
}
2023-02-27 13:21:19 +00:00
Song {
}
Album {
}
Artist {
}
Label {
}
Source {
}
2023-03-24 18:07:37 +00:00
Source }o--|| Song : ""
Source }o--|| Lyrics : ""
Source }o--|| Album : ""
Source }o--|| Artist : ""
Source }o--|| Label : ""
2023-02-27 13:49:12 +00:00
Song }o--o{ Album : AlbumSong
Album }o--o{ Artist : ArtistAlbum
2023-03-24 18:07:37 +00:00
Song }o--o{ Artist : "ArtistSong (features)"
2023-02-27 13:49:12 +00:00
Label }o--o{ Album : LabelAlbum
Label }o--o{ Artist : LabelSong
2023-03-24 18:07:37 +00:00
Song ||--o{ Lyrics : ""
Song ||--o{ Target : ""
2023-02-27 13:21:19 +00:00
```
Ok now this **WILL** look intimidating, thus I break it down quickly.
*That is also the reason I didn't add all Attributes here.*
The most important Entities are:
- Song
- Album
- Artist
- Label
All of them *(and Lyrics)* can have multiple Sources, and every Source can only Point to one of those Element.
The `Target` Entity represents the location on the hard drive a Song has. One Song can have multiple download Locations.
The `Lyrics` Entity simply represents the Lyrics of each Song. One Song can have multiple Lyrics, e.g. Translations.
Here is the simplified Diagramm without only the main Entities.
```mermaid
---
title: simplified Music Data
---
erDiagram
Song {
}
Album {
}
Artist {
}
Label {
}
2023-02-27 13:49:12 +00:00
Song }o--o{ Album : AlbumSong
Album }o--o{ Artist : ArtistAlbum
2023-03-24 18:07:37 +00:00
Song }o--o{ Artist : "ArtistSong (features)"
2023-02-27 13:21:19 +00:00
2023-02-27 13:49:12 +00:00
Label }o--o{ Album : LabelAlbum
Label }o--o{ Artist : LabelSong
2023-02-27 13:21:19 +00:00
```
2023-03-10 09:54:15 +00:00
Looks way more manageable, doesn't it?
2023-02-27 13:21:19 +00:00
The reason every relation here is a `n:m` *(many to many)* relation is not, that it makes sense in the aspekt of modeling reality, but to be able to put data from many Sources in the same Data Model.
2023-03-10 09:54:15 +00:00
Every Service models Data a bit different, and projecting a one-to-many relationship to a many to many relationship without data loss is easy. The other way around it is basically impossible
2023-02-27 13:21:19 +00:00
2023-02-27 13:29:09 +00:00
## Data Objects
> Not 100% accurate yet and *might* change slightly
2023-01-23 15:57:00 +00:00
2023-03-09 15:14:38 +00:00
### Creation
2023-01-23 15:57:00 +00:00
```python
2023-06-23 11:31:49 +00:00
# needs to be added
2023-01-23 15:57:00 +00:00
```
2023-03-09 15:14:38 +00:00
2023-06-23 11:31:49 +00:00
If you just want to start implementing, then just use the code example I provided, I don't care.
For those who don't want any bugs and use it as intended *(which is recommended, cuz I am only one person so there are defs bugs)* continue reading, and read the whole documentation, which may exist in the future xD
2023-03-10 11:36:28 +00:00
2022-11-23 19:12:38 +00:00
2023-01-13 13:37:15 +00:00
[i10]: https://github.com/HeIIow2/music-downloader/issues/10
2022-11-23 19:13:16 +00:00
[i2]: https://github.com/HeIIow2/music-downloader/issues/2