new build and upload

build.sh

@@ -5,10 +5,10 @@ python3 -m build
 
 echo "uploading............"
 python3 -m pip install --upgrade twine
-# twine upload dist/music_kraken*
+twine upload dist/music_kraken*
 
-twine upload --repository testpypi dist/music_kraken*
+# twine upload --repository testpypi dist/music_kraken*
-exit
+# exit
 
 echo "pushing............"
 git add .

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "music_kraken"
-version = "1.1.4"
+version = "1.2.0"
 authors = [
   { name="Hellow2", email="Hellow2@outlook.de" },
 ]

src/music_kraken.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: music-kraken
-Version: 1.1.4
+Version: 1.2.0
 Summary: An extensive music downloader crawling the internet. It gets its metadata from a couple metadata provider, and it scrapes the audiofiles.
 Home-page: https://github.com/HeIIow2/music-downloader
 Author: Hellow2
@@ -31,6 +31,10 @@ pip install music-kraken
 music-kraken
 ```
 
+### Notes for WSL
+
+If you choose to run it in WSL, make sure ` ~/.local/bin` is added to your `$PATH` [#2][i2]
+
 ## Quick-Guide
 
 **Genre:** First the cli asks you to input a gere you want to download to. The options it gives you (if it gives you any) are all the folders you got in the music directory. You also can just input a new one.
@@ -54,35 +58,191 @@ 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
+if you simply want to run the builtin minimal cli just do this:
-  - shared (equivalent to global variables and constants)
+```python
-  - config
+mk.cli()
-  - database
+```
-  - some static methods that are in general useful for me
+
-- tagging
+### Search for Metadata
-  - song (within a class Song used to get and set the metadata of mp3 files)
+
-- metadata
+The whole programm takes the data it processes further from the cache, a sqlite database.
-  - search
+So before you can do anything, you will need to fill it with the songs you want to download.  
-  - fetch
+For now the base of everything is musicbrainz, so you need to get the
-- target
+musicbrainz id and the type the id corresponds to (artist/release group/release/track).
-- audio_source 
+To get this you first have to initialize a search object (`music_kraken.metadata.metadata_search.Search`).
-  - fetch_source
+
-  - fetch_audio
+```python
-  - sources
+search_object = mk.metadata.metadata_search.Search()
-    - musify
+```
-    - youtube
+
-- lyrics
+Then you need an initial "text search" to get some options you can choose from. For
-  - lyrics
+this you can either specify artists releases and whatever directly with one of the following functions:
-  - genius (will eventually be moved in a folder with lyric sources)
+
+```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.
+
+### 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:
+
+```python
+# adds file path, file directory and the genre to the database 
+mk.target.set_target.UrlPath(genre="some test genre")
+```
+
+The concept of genres is too loose, to definitly 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 (*actually its a class but it doesn't make any difference*).
+
+### Get the Download Links / Audio Sources
+
+This is most likely the most usefull and unique feature of this Project. If the cache is filled you can get audio sources for the songs you only have the metadata. This works for most songs. I'd guess for about 97% (?)
+
+```python
+# this is how you do it.
+mk.audio_source.fetch_source.Download()
+``` 
+
+Now the audio sources are int the cache, and you can get them as mentioned above  (`Song.sources: List[Source]`). 
+
+### Downloading the Audio
+
+If the target paths fields and audio sources are set in the database field, then the audio files can just be downloaded and automatically tagged like this:
+
+```python
+mk.audio_source.fetch_audio.Download()
+
+# after that the lyrics can be added
+mk.lyrics.lyrics.fetch_lyrics()
+```
 
 ---
 
@@ -179,3 +339,6 @@ To get the Lyrics, I scrape them, and put those in the USLT ID3 Tags of for exam
 ### Genius
 
 For the lyrics source the page [https://genius.com/](https://genius.com/) is easily sufficient. It has most songs. Some songs are not present though, but that is fine, because the lyrics are optional anyways.
+
+
+[i2]: https://github.com/HeIIow2/music-downloader/issues/2

src/music_kraken/audio_source/fetch_source.py

@@ -55,12 +55,15 @@ class Download:
                 self.add_url(musify_url, 'musify', id_)
                 continue
             """
+            sucess = False
             for src in AUDIO_SOURCES:
                 res = Download.fetch_from_src(song, src)
                 if res is not None:
+                    sucess = True
                     Download.add_url(res, src, id_)
 
-            logger.warning(f"Didn't find any sources for {song}")
+            if not sucess:
+                logger.warning(f"Didn't find any sources for {song}")
 
     @staticmethod
     def fetch_from_src(song, src):