✨ tiddl3 (#194)

examples/download_track.py

@@ -0,0 +1,37 @@
+from pathlib import Path
+
+from tiddl.core.utils import get_track_stream_data
+from tiddl.core.metadata import add_track_metadata
+from tiddl.core.api.models import TrackQuality
+
+# we reuse Tidal API from another example
+from .fetch_api import api
+
+# Congratulations by Post Malone
+TRACK_ID = 77662595
+QUALITY: TrackQuality = "LOSSLESS"
+
+if __name__ == "__main__":
+    # fetch track_stream
+    track_stream = api.get_track_stream(TRACK_ID, QUALITY)
+
+    # download bytes to stream_data and get the file extension
+    stream_data, file_extension = get_track_stream_data(track_stream)
+
+    filename = f"{TRACK_ID}_{track_stream.audioQuality}"
+
+    # get file path that is located at our current directory
+    # with filename: TRACK_ID_QUALITY.EXTENSION
+    track_path = Path(filename).with_suffix(file_extension)
+
+    # write data from the track_stream to our file
+    track_path.write_bytes(stream_data)
+
+    # fetch some informations about our track like title etc.
+    track = api.get_track(TRACK_ID)
+
+    # add the metadata to our saved file.
+    # note that not every data is added such as cover or lyrics.
+    add_track_metadata(track_path, track)
+
+    # Congratulations if it works on your machine

examples/download_video.py

@@ -0,0 +1,43 @@
+from pathlib import Path
+
+from tiddl.core.metadata import add_video_metadata
+from tiddl.core.api.models.base import VideoQuality
+from tiddl.core.utils import get_video_stream_data
+from tiddl.core.utils.ffmpeg import convert_to_mp4, is_ffmpeg_installed
+
+# we reuse Tidal API from another example
+from .fetch_api import api
+
+# Old Town Road by Lil Nas X
+VIDEO_ID = 113483426
+QUALITY: VideoQuality = "HIGH"
+
+if __name__ == "__main__":
+    print("fetching video_stream")
+    video_stream = api.get_video_stream(video_id=VIDEO_ID, quality=QUALITY)
+
+    # download bytes to stream_data and get the file extension
+    print("downloading video_stream data")
+    stream_data = get_video_stream_data(video_stream)
+
+    filename = f"{VIDEO_ID}_{QUALITY}"
+
+    # get file path that is located at our current directory
+    video_path = Path(filename).with_suffix(".ts")
+
+    # write data from the video_stream to our file
+    print(f"saving to {video_path}")
+    video_path.write_bytes(stream_data)
+
+    if is_ffmpeg_installed():
+        # convert the file from .ts to .mp4
+        print("converting to mp4")
+        video_path = convert_to_mp4(video_path)
+
+        # fetch some informations about our video like title etc.
+        print("getting video metadata")
+        video = api.get_video(VIDEO_ID)
+
+        # add the metadata to our saved file.
+        print("saving metadata")
+        add_video_metadata(video_path, video)

examples/fetch_api.py

@@ -0,0 +1,47 @@
+from tiddl.core.api import TidalAPI, TidalClient
+
+# we will utilize some functions from tiddl cli
+# and use `APP_PATH` that is located at our /home_directory/.tiddl
+from tiddl.cli.utils.auth import load_auth_data
+from tiddl.cli.const import APP_PATH
+
+# !! remember to be logged in, use `tiddl auth login`
+# it will save auth token in /home_directory/.tiddl/auth.json
+
+# in case your token expired, then use `tiddl auth refresh`
+
+# load our token, country code and user id from file
+auth_data = load_auth_data()
+
+# we make sure auth_data is not empty = we are logged in
+
+assert auth_data.token
+assert auth_data.country_code
+assert auth_data.user_id
+
+# we create Client for our API.
+# this is custom client that can cache requests
+# to make the API more efficient
+
+client = TidalClient(
+    token=auth_data.token,
+    cache_name=APP_PATH / "api_cache",  # path to cache api requests
+    debug_path=APP_PATH / "api_debug",  # optional, used for debugging api
+)
+
+# this is our Tidal API that will call the endpoints
+
+api = TidalAPI(
+    client,
+    country_code=auth_data.country_code,
+    user_id=auth_data.user_id,
+)
+
+if __name__ == "__main__":
+    # make the API call
+    session = api.get_session()
+
+    # every data from the api is `pydantic` model
+    print(f"session id: {session.sessionId}")
+
+    # see every available endpoint at `tiddl.core.api`

examples/track_templating.py

@@ -0,0 +1,26 @@
+from tiddl.core.utils.format import format_template
+
+# we reuse Tidal API from another example
+from .fetch_api import api
+
+ALBUM_ID = 465173294
+
+
+if __name__ == "__main__":
+    album = api.get_album(ALBUM_ID)
+    album_items = api.get_album_items(ALBUM_ID)
+
+    TEMPLATE = "{album.artists}/{album.title}, {album.date:%Y}/{item.number:02d}. {item.artists} - {item.title} ({custom_field})"
+
+    for album_item in album_items.items:
+        track = album_item.item
+
+        print(
+            format_template(
+                template=TEMPLATE,
+                item=track,
+                album=album,
+                with_asterisk_ext=False,
+                custom_field="custom_field",
+            )
+        )