diff --git a/README.md b/README.md index c3b7f06..3519f34 100644 --- a/README.md +++ b/README.md @@ -40,35 +40,156 @@ After you chose either an artist, a release group, a release or a track by its i --- -## Programming interface +## Programming Interface / use as Library -If you want to use this project, or parts from it in youre own projects from it, +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 guarantee) -### Modules +Music Kraken can be imported like this: +```python +import music_kraken as mk +``` -- utils - - shared (equivalent to global variables and constants) - - config - - database - - some static methods that are in general useful for me -- tagging - - song (within a class Song used to get and set the metadata of mp3 files) -- metadata - - search - - fetch -- target -- audio_source - - fetch_source - - fetch_audio - - sources - - musify - - youtube -- lyrics - - lyrics - - genius (will eventually be moved in a folder with lyric sources) +if you simply want to run the builtin minimal cli just do this: +```python +mk.cli() +``` + +### Search for Metadata + +The whole programm 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. +For now the base of everything is musicbrainz, so you need to get the +musicbrainz id and the type the id corresponds to (artist/release group/release/track). +To get this you first have to initialize a search object (`music_kraken.metadata.metadata_search.Search`). + +```python +search_object = mk.metadata.metadata_search.Search() +``` + +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: + +```python +# 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 possible methods return an instance of `MultipleOptions`, which can be directly converted to a string. + +```python +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 `Search.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*** + +```python +# 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: + +```python +multiple_options = search.get_previous_options() +``` + +### Downloading Metadata / Filling up the Cache + +If you selected the Option you want with `Search.choose(i)`, you can +finally download the metadata of either: + - an artist (the whole discography) + - a release group + - a release + - a track/recording +To download you need the selected Option Object (`music_kraken.metadata.metadata_search.Option`) +it is simply stored in `Search.current_option`. + +If you already know what you want to download you can skip all the steps above and just create +a dictionary like this and use it later (*might change and break after I add multiple metadata sources which I will*): +```python +download_dict = { + 'type': option_type, + 'id': musicbrainz_id +} +``` +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, ITS CASE SENSITIVE** + +The musicbrainz id is just the id of the object from musicbrainz. + +```python +# in this example I will choose the previous selected option. +option_to_download = search_object.current_option +print(option_to_download) + +download_dict = { + 'type': option_to_download.type, + 'id': option_to_download.id +} +``` + +If you got the Option instance you want to download and created the dictionary, then downloading the metadata is really straight +forward, so I just show the code. + +```python +# I am aware of abstrackt classes +metadata_downloader = mk.metadata.metadata_fetch.MetadataDownloader() +metadata_downloader.download(download_dict) +``` + +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. +You can get the database object like this: + +```python +cache = mk.database.temp_database.temp_database +print(cache) +``` + +When fetching any song data from the cache, you will get it as Song +object (music_kraken.database.song.Song). There are multiple methods +to get different sets of Songs. The names explain the methods pretty +well: + +```python +# 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 --- diff --git a/src/music_kraken/__init__.py b/src/music_kraken/__init__.py index 99162ec..e77ccdc 100644 --- a/src/music_kraken/__init__.py +++ b/src/music_kraken/__init__.py @@ -17,7 +17,6 @@ from .audio_source import ( ) from .lyrics import lyrics - logging.getLogger("musicbrainzngs").setLevel(logging.WARNING) musicbrainzngs.set_useragent("metadata receiver", "0.1", "https://github.com/HeIIow2/music-downloader") @@ -30,6 +29,7 @@ def get_existing_genre(): return valid_directories + def help_search_metadata(): msg = """ - - - Type the command you want to execute - - - @@ -59,14 +59,15 @@ def execute_input(_input: str, search: metadata_search.Search) -> bool: print() print(search.choose(int(_input))) return False - if _input == ".." : + if _input == "..": print() print(search.get_previous_options()) return False - + print() print(search.search_from_query(_input)) + def search_for_metadata(): search = metadata_search.Search()