# Programming Interface / Use as Library
If you want to use this project, or parts from it in your own projects from it,
make sure to be familiar with [Python Modules](https://docs.python.org/3/tutorial/modules.html).
Further and better documentation including code examples are yet to come, so here is the rough
module structure for now. (Should be up-to-date, but no guarantees)
If you simply want to run the builtin minimal cli just do this:
from music_kraken import cli
cli()
## Search for Metadata
The whole program takes the data it processes further from the cache, a sqlite database.
So before you can do anything, you will need to fill it with the songs you want to download (*or create song objects manually, but more on that later*).
For now the base of everything is [musicbrainz][mb], so you need to get the musicbrainz `id` and `type`. The `id` corresponds to either
- an artist
- a release group
- a release
- a recording/track).
To get this info, you first have to initialize a search object (`music_kraken.MetadataSearch`).
search_object = music_kraken.MetadataSearch()
Then you need an initial "text search" to get some options you can choose from. For
this you can either specify artists releases and whatever directly with one of the following functions:
# you can directly specify artist, release group, release or recording/track
multiple_options = search_object.search_from_text(artist=input("input the name of the artist: "))
# you can specify a query see the simple integrated cli on how to use the query
multiple_options = search_object.search_from_query(query=input("input the query: "))
Both methods return an instance of `MultipleOptions`, which can be directly converted to a string.
print(multiple_options)
After the first "*text search*" you can either again search the same way as before,
or you can further explore one of the options from the previous search.
To explore and select one options from `MultipleOptions`, simply call `MetadataSearch.choose(self, index: int)`.
The index represents the number in the previously returned instance of MultipleOptions.
The selected Option will be selected and can be downloaded in the next step.
*Thus, this has to be done **after either search_from_text or search_from_query***
# choosing the best matching band
multiple_options = search_object.choose(0)
# choosing the first ever release group of this band
multiple_options = search_object.choose(1)
# printing out the current options
print(multiple_options)
This process can be repeated indefinitely (until you run out of memory).
A search history is kept in the Search instance. You could go back to
the previous search (without any loading time) like this:
multiple_options = search_object.get_previous_options()
## Downloading Metadata / Filling up the Cache
You can download following metadata:
- an artist (the whole discography)
- a release group
- a release
- a track/recording
If you got an instance of `MetadataSearch`, like I elaborated [previously](#search-for-metadata), downloading every piece of metadata from the currently selected Option is really quite easy.
from music_kraken import fetch_metadata_from_search
# this is it :)
music_kraken.fetch_metadata_from_search(search_object)
If you already know what you want to download you can skip the search instance and simply do the following.
from music_kraken import fetch_metadata
# might change and break after I add multiple metadata sources which I will
fetch_metadata(id_=musicbrainz_id, type=metadata_type)
The option type is a string (*I'm sorry for not making it an enum I know its a bad pratice*), which can
have following values:
- 'artist'
- 'release_group'
- 'release'
- 'recording'
**PAY ATTENTION TO TYPOS, IT'S CASE SENSITIVE**
The musicbrainz id is just the id of the object from musicbrainz.
After following those steps, it might take a couple seconds/minutes to execute, but then the Cache will be filled.
## Cache / Temporary Database
All the data, the functions that download stuff use, can be gotten from the temporary database / cache.
The cache can be simply used like this:
music_kraken.cache
When fetching any song data from the cache, you will get it as Song
object (music_kraken.Song). There are multiple methods
to get different sets of Songs. The names explain the methods pretty
well:
from music_kraken import cache
# gets a single track specified by the id
cache.get_track_metadata(id: str)
# gets a list of tracks.
cache.get_tracks_to_download()
cache.get_tracks_without_src()
cache.get_tracks_without_isrc()
cache.get_tracks_without_filepath()
The id always is a musicbrainz id and distinct for every track.
## Setting the Target
By default the music downloader doesn't know where to save the music file, if downloaded. To set those variables (the directory to save the file in and the filepath), it is enough to run one single command:
from music_kraken import set_target
# adds file path, file directory and the genre to the database
set_target(genre="some test genre")
The concept of genres is too loose, to definitely say, this band exclusively plays this genre, or this song is this genre. This doesn't work manually, this will never work automatically. Thus, I've decided to just use the genre as category, to sort the artists and songs by. Most Music players support that.
As a result of this decision you will have to pass the genre in this function.
## Get Audio
This is most likely the most useful and unique feature of this Project. If the cache is filled, you can get audio sources for the songs you only have the metadata, and download them. This works for most songs. I'd guess for about 97% (?)
First of you will need a List of song objects `music_kraken.Song`. As [mentioned above](#cache--temporary-database), you could get a list like that from the cache.
# Here is an Example
from music_kraken import (
cache,
fetch_sources,
fetch_audios
)
# scanning pages, searching for a download and storing results
fetch_sources(cache.get_tracks_without_src())
# downloading all previously fetched sources to previously defined targets
fetch_audios(cache.get_tracks_to_download())
*Note:*
To download audio two cases have to be met:
1. [The target](#setting-the-target) has to be set beforehand
2. The sources have to be fetched beforehand
---
