### GET /settings-read example response Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example JSON response from the GET /settings-read endpoint, showing the full current configuration including api, download, logging, metadata, and webui sections. ```json { "config": { "api": { "deezer": true, "genius": true, "genius_album_check": true, "genius_token": "", "genius_use_official": false, "max_retry": 3, "mb_retry_artist_name_only": false, "musicbrainz": true }, "download": { "always_search_by_query": false, "check_if_file_exists": true, "cookies_from_browser": "", "cookies_path": "", "disable_download": false, "download_archive": "", "fetch_albums": false, "format": "m4a", "id3_version": 3, "include_other_artists": false, "include_singles": false, "number_downloaders": 1, "output": "{album_artist}/{album_artist} - {song}", "output_dir": "/home/chemgull/Documents/Coding/Python/SomeDL/downloads/downloads/", "prefer_playlist": false, "quality": 5, "queue_size": 2, "range": [], "sleep": 3, "sleep_warn": true, "strict_url_download": false, "sync_files": [ "/home/chemgull/.config/SomeDL/myPlaylist3_sync.json" ] }, "logging": { "config_version": 7, "download_report": 2, "level": "INFO", "log_level": 4 }, "metadata": { "album_artist": true, "artist_separator": "; ", "copyright": true, "cover_art_file": false, "cover_art_size": "l", "ffmpeg_metadata": false, "genre": true, "isrc": true, "lrc_file": false, "lyrics": false, "lyrics_fallback_source": "lrclib", "lyrics_id3_synced_uslt_fallback": true, "lyrics_source": "youtube", "lyrics_type": "plain", "multiple_artists": false, "synced_lyrics_metadata": true }, "webui": { "browser": "chromium", "host": "127.0.0.1", "open_browser": false, "port": 5000 } } } ``` -------------------------------- ### GET /webui-load-config example response Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example JSON response returned by GET /webui-load-config with status 200 OK. Shows the active theme and custom theme definitions. ```json { "active_theme": "SomeDL Dark", "custom_themes": { "Another Theme": { "theme": "dark", "color-main": "#590058", "color-main-highlight": "#711196", "color-background": "#1e1c20", "color-background-highlight": "#2d2b2f", "color-button": "#0f0f0f", "color-border": "#767676", "color-text": "#FFFFFF", "color-dlbar-1": "#711196", "color-dlbar-2": "#ac3011" } } } ``` -------------------------------- ### Install FFmpeg with winget Source: https://somedl.readthedocs.io/en/latest/installation/requirements.html Fastest way to install FFmpeg on Windows. The winget command is 'winget install ffmpeg'. If this fails, a manual installation guide is linked. ```bash winget install ffmpeg ``` -------------------------------- ### GET /status - Example response Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example JSON response from the /status endpoint showing active_items with process statuses and finished_items with status and output path. ```json { "active_items": { "17806688160307190000001": { "text": "4/0 Delain - Not Enough", "data": { "album": { "message": "Nothing", "status": "success" }, "get_lyrics": { "status": "skipped", "message": "Nothing" }, "musicbrainz": { "status": "success", "message": "Nothing" }, "deezer": { "status": "success", "message": "Nothing" }, "wait_queue": { "status": "hide", "message": "Nothing" }, "downloading": { "status": "success", "message": "Nothing" }, "albumart": { "status": "success", "message": "Nothing" }, "addmetadata": { "status": "success", "message": "Nothing" } } }, "17771447553066950000002": { "text": "5/0 The Warning - EVOLVE", "data": { "album": { "status": "success", "message": "Nothing" }, "get_lyrics": { "status": "skipped", "message": "Nothing" }, "musicbrainz": { "status": "success", "message": "Nothing" }, "deezer": { "status": "success", "message": "Nothing" }, "wait_queue": { "status": "hide", "message": "Nothing" }, "downloading": { "status": "active", "message": "yt-dlp: Postprocessing (Got 3.29MiB at [green]\u001b[0;32m3.83MiB/s\u001b[0m[/])" } } } }, "finished_items": { "17806688160307190000001": ["success", "/path/to/file.ext"], "17806688160354710000001": ["failed", null], "17806688160397410000001": ["already_downloaded", null], "17806688160416870000001": ["already_downloaded", "/path/to/file.ext"], }, "items_in_queue": 5 } ``` -------------------------------- ### POST /resume-download example response Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example JSON response for the resume-download endpoint. Returns a message indicating the download is resumed. ```json { "message": "Download resumed" } ``` -------------------------------- ### POST /settings-apply example response Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example JSON response from the POST /settings-apply endpoint, indicating that settings were applied successfully. ```json { "message": "applied settings" } ``` -------------------------------- ### Example response for GET /get-version endpoint Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Shows the JSON response containing the SomeDL version. ```json { "v": "1.5.0" } ``` -------------------------------- ### GET /get-downloader-state example response Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example JSON response for the get-downloader-state endpoint. Contains a boolean field is_running indicating whether the downloader is running or paused. ```json { "is_running": true } ``` -------------------------------- ### Install SomeDL via pip on Windows Source: https://somedl.readthedocs.io/en/latest/installation/installation.html Installs SomeDL using pip. Use this on Windows systems. ```bash pip install somedl ``` -------------------------------- ### Example response for GET /get-history endpoint Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Shows the JSON response containing the download history of the current session, including success, already downloaded, and failed lists. ```json { "metadata_success_list": [ { "album_art": [ { "height": 60, "url": "https://yt3.googleusercontent.com/S0y9a8Dv3SlLbxf0SAAfY4UmgHLHxto-77tyThyl0aQaFKVz8rrruDsdH72j_ibf6qJdGi2yh8r1rDfr=w60-h60-l90-rj", "width": 60 }, { "height": 120, "url": "https://yt3.googleusercontent.com/S0y9a8Dv3SlLbxf0SAAfY4UmgHLHxto-77tyThyl0aQaFKVz8rrruDsdH72j_ibf6qJdGi2yh8r1rDfr=w120-h120-l90-rj", "width": 120 } ] } ] } ``` -------------------------------- ### Install SomeDL via python -m pip on Windows Source: https://somedl.readthedocs.io/en/latest/installation/installation.html Alternative Windows installation command using python -m pip. ```bash python -m pip install somedl ``` -------------------------------- ### Install SomeDL via pipx on Linux Source: https://somedl.readthedocs.io/en/latest/installation/installation.html Installs SomeDL using pipx on Linux, as it is not packaged in any repository. ```bash pipx install somedl ``` -------------------------------- ### POST /pause-download example response Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example JSON response for the pause-download endpoint. Returns a message indicating the download is paused. ```json { "message": "Download paused" } ``` -------------------------------- ### GET /status - Example request (JavaScript) Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Fetch the current processing status from the /status endpoint. Returns a JSON object with active_items, finished_items, and items_in_queue. ```javascript const res = await fetch("/status"); const data = await res.json(); ``` -------------------------------- ### GET /get-history Response Source: https://somedl.readthedocs.io/en/latest/_sources/code_documentation/flask.rst.txt Example response for the /get-history endpoint. ```json { "metadata_success_list": [ { "album_art": [ { "height": 60, ``` -------------------------------- ### Start WebUI with `somedl web` Source: https://somedl.readthedocs.io/en/latest/_sources/usage/general_usage.rst.txt Launch the WebUI server; a browser window opens with default address http://127.0.0.1:5000/ and can be stopped with Ctrl+C or the shutdown button. ```bash somedl web ``` -------------------------------- ### POST /get-download-report example response Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example response from the POST /get-download-report endpoint. The response contains an html string field (note the misspelling 'hmtl') that holds the generated download report. A 200 OK status indicates success, while a 500 Internal Server Error indicates a failure to generate the report. ```json { "hmtl": "", } ``` -------------------------------- ### Run the new-template utility Source: https://somedl.readthedocs.io/en/latest/usage/howto.html Execute this command in your terminal to start the interactive process for moving or copying files to a new storage template. ```bash somedl new-template ``` -------------------------------- ### GET /webui-load-config Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Loads current webui configs. ```APIDOC ## GET /webui-load-config ### Description Loads current webui configs. ### Method GET ### Endpoint /webui-load-config ### Parameters None ### Response #### Success Response (200) - **Content-Type** (string) - application/json #### Response Example ``` { "active_theme": "SomeDL Dark", "custom_themes": { "Another Theme": { "theme": "dark", "color-main": "#590058", "color-main-highlight": "#711196", "color-background": "#1e1c20", "color-background-highlight": "#2d2b2f", "color-button": "#0f0f0f", "color-border": "#767676", "color-text": "#FFFFFF", "color-dlbar-1": "#711196", "color-dlbar-2": "#ac3011" } } } ``` ``` -------------------------------- ### POST /clear-queue example response Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example JSON response for the clear-queue endpoint. Returns a message indicating the queue is cleared. ```json { "message": "Queue cleared" } ``` -------------------------------- ### Example response for /download endpoint Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Shows the JSON structure returned by the /download endpoint, including an 'active' dictionary and a 'queue' list with song details. ```json { "active": { "17806688160307332000002": { "data": {}, "text": "2/0 Delain - We Are The Others (Radio Version)" } }, "queue": [ { "somedl_id": "17806703611854036000001", "text_query": "delain - the cold", "video_type": "Search query", "video_type_original": "Search query" }, { "album_id": "MPREb_fMsob6AXjNV", "album_name": "Ego", "artist_all_names": [ "The Warning" ], "artist_id": "UCmZbBc8qMj0v9Q6dC-kw4Xg", "artist_name": "The Warning", "lyrics_id": "MPLYt_fMsob6AXjNV-1", "original_url_id": "u-BMzP-RLd4", "somedl_id": "17806707385822792000001", "song_id": "u-BMzP-RLd4", "song_title": "Ego", "song_title_clean": "Ego", "video_type": "MUSIC_VIDEO_TYPE_ATV", "video_type_original": "MUSIC_VIDEO_TYPE_ATV", "yt_url": "https://www.youtube.com/watch?v=u-BMzP-RLd4" } ] } ``` -------------------------------- ### Warning: No supported JavaScript runtime could be found Source: https://somedl.readthedocs.io/en/latest/_sources/usage/faq.rst.txt Indicates that Deno is not installed or not correctly configured. Only deno is enabled by default; to use another runtime, add the --js-runtimes RUNTIME[:PATH] option. YouTube extraction without a JS runtime has been deprecated. ```text WARNING - >_yt-dlp: [youtube] No supported JavaScript runtime could be found. Only deno is enabled by default; to use another runtime add –js-runtimes RUNTIME[:PATH] YouTube extraction without a JS runtime has been deprecated. ``` -------------------------------- ### Error: Did not get any data blocks Source: https://somedl.readthedocs.io/en/latest/_sources/usage/faq.rst.txt Usually related to the above warning. yt-dlp typically recovers automatically. ```text ERROR - >_yt-dlp: Did not get any data blocks ``` -------------------------------- ### GET /get-version Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Returns the SomeDL version. ```APIDOC ## GET /get-version ### Description Returns SomeDL version. ### Method GET ### Endpoint /get-version ### Response #### Success Response (200) - **v** (_string_) - Version string. #### Response Example ``` { "v": "1.5.0" } ``` ### Error Handling #### Status Codes - 200 OK – Shutdown successfully triggered #### Response Headers - Content-Type – application/json ``` -------------------------------- ### GET /settings-read Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Retrieves the current SomeDL settings, including configuration options not present in the config file. ```APIDOC ## GET /settings-read ### Description Returns current SomeDL settings. Also includes configuration options not in the config file. ### Method GET ### Endpoint /settings-read ### Response #### Success Response (200) - **config** (object) - The current settings configuration. #### Response Example ``` { "config": { "api": { "deezer": true, "genius": true, "genius_album_check": true, "genius_token": "", "genius_use_official": false, "max_retry": 3, "mb_retry_artist_name_only": false, "musicbrainz": true }, "download": { "always_search_by_query": false, "check_if_file_exists": true, "cookies_from_browser": "", "cookies_path": "", "disable_download": false, "download_archive": "", "fetch_albums": false, "format": "m4a", "id3_version": 3, "include_other_artists": false, "include_singles": false, "number_downloaders": 1, "output": "{album_artist}/{album_artist} - {song}", "output_dir": "/home/chemgull/Documents/Coding/Python/SomeDL/downloads/downloads/", "prefer_playlist": false, "quality": 5, "queue_size": 2, "range": [], "sleep": 3, "sleep_warn": true, "strict_url_download": false, "sync_files": [ "/home/chemgull/.config/SomeDL/myPlaylist3_sync.json" ] }, "logging": { "config_version": 7, "download_report": 2, "level": "INFO", "log_level": 4 }, "metadata": { "album_artist": true, "artist_separator": "; ", "copyright": true, "cover_art_file": false, "cover_art_size": "l", "ffmpeg_metadata": false, "genre": true, "isrc": true, "lrc_file": false, "lyrics": false, "lyrics_fallback_source": "lrclib", "lyrics_id3_synced_uslt_fallback": true, "lyrics_source": "youtube", "lyrics_type": "plain", "multiple_artists": false, "synced_lyrics_metadata": true }, "webui": { "browser": "chromium", "host": "127.0.0.1", "open_browser": false, "port": 5000 } } } ``` ``` -------------------------------- ### Example response for POST /shutdown endpoint Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Shows the JSON response returned when a shutdown is successfully triggered. ```json { "message": "shutdown triggered" } ``` -------------------------------- ### POST /yt-download success response (200) Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example success response containing a list of songs to download with prefetched metadata, including album, artist, and video details. ```json { "song_list": [ { "album_id": "MPREb_B9YcEZY20ip", "album_name": "Dark Waters", "artist_all_names": [ "Delain" ], "artist_id": "UCPIXyGsEUrGIz7olJ1d7-Ig", "artist_name": "Delain", "lyrics_id": "MPLYt_B9YcEZY20ip-1", "original_url_id": "WOZOwTG9dmU", "somedl_id": "17806739333906158000001", "song_id": "WOZOwTG9dmU", "song_title": "Hideaway Paradise", "song_title_clean": "Hideaway Paradise", "video_type": "MUSIC_VIDEO_TYPE_ATV", "video_type_original": "MUSIC_VIDEO_TYPE_ATV", "yt_url": "https://www.youtube.com/watch?v=WOZOwTG9dmU" } ] } ``` -------------------------------- ### Example sync file JSON Source: https://somedl.readthedocs.io/en/latest/_sources/usage/howto.rst.txt A JSON sync file that overrides config settings for specific playlists, e.g., setting format to 'best/opus' and output directory to '/home/user/Music/Concert/'. The 'playlists' array contains URLs of playlists to sync. ```json { "playlists": [ "https://...", "https://...", ], "format": "best/opus", "output_dir": "/home/user/Music/Concert/" } ``` -------------------------------- ### POST /yt-get-artist Request Body Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example request body for looking up an artist by their ID. ```json { "artist_id": "UCRAHc1Aild5p1Zmy2rAgVmA", } ``` -------------------------------- ### POST /remove-item request body and example response Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example request body and response for the remove-item endpoint. The request body includes a somedl_id field, and the response returns a message indicating the item is removed. ```json { "somedl_id": "17806724760830844000001" } ``` ```json { "message": "Item removed" } ``` -------------------------------- ### POST /webui-save-config request body Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example JSON request body for POST /webui-save-config. Contains the webui_settings object with active_theme and custom_themes. ```json { "webui_settings": { "active_theme": "SomeDL Dark", "custom_themes": { "My theme": { "theme": "dark", "color-main": "#590058", "color-main-highlight": "#711196", "color-background": "#1e1c20", "color-background-highlight": "#2d2b2f", "color-button": "#0f0f0f", "color-border": "#767676", "color-text": "#FFFFFF", "color-dlbar-1": "#711196", "color-dlbar-2": "#ac3011" } } } } ``` -------------------------------- ### POST /setlist-mbid Success Response Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example of a successful 200 OK response containing setlist details. ```json { "result": { "itemsPerPage": 20, "page": 1, "setlist": [ { "artist": { "disambiguation": "Dutch symphonic metal band", "mbid": "3b0e8f01-3fd9-4104-9532-1e4b526ce562", "name": "Delain", "sortName": "Delain", "url": "https://www.setlist.fm/setlists/delain-1bd6fd7c.html" }, "eventDate": "18-10-2025", "id": "5b59e7ec", "lastUpdated": "2025-10-19T07:37:47.657+0000", "sets": { "set": [ { "song": [ { "name": "The Cold" }, { "name": "Suckerpunch" }, { "name": "The Reaping" }, { "name": "Dance With the Devil" }, { "name": "Burning Bridges" }, { "name": "Creatures" }, { "name": "Stardust" }, { "info": "Acoustic", "name": "Start Swimming" }, { "name": "Underland" }, { "name": "Get the Devil Out of Me" }, { "name": "Your Body Is a Battleground", "with": { "disambiguation": "Italian-born singer based in Finland", "mbid": "1dc6c8c8-548f-4d1a-87ea-e557cb7064b9", "name": "Paolo Ribaldini", "sortName": "Ribaldini, Paolo", "url": "https://www.setlist.fm/setlists/paolo-ribaldini-13cac925.html" } }, { ``` -------------------------------- ### POST /yt-get-artist Success Response Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example of a successful 200 OK response containing artist information. ```json { "result": { "albums": { "browseId": "MPADUCRAHc1Aild5p1Zmy2rAgVmA", "params": "ggMIegYIARoCAQI%3D", "results": [ { "browseId": "MPREb_QUSFPk9bVbr", "playlistId": "OLAK5uy_nAXNlW2rUoESvV8iAAdhTk7shLE2OA4TY", "thumbnails": [ { "height": 226, "url": "https://yt3.googleusercontent.com/YxmTS8kRUvzKNgFWCRPtbXU4Qgyf6hSs7STYPGN7aI5mNKD3LNXOHuZWD5B9MLeiyn2J_RUp3VYsEJiV=w226-h226-l90-rj", "width": 226 }, { ``` -------------------------------- ### POST /setlist-artist Success Response Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example of a successful 200 OK response containing a list of artists. ```json { "result": { "artist": [ { "disambiguation": "Dutch symphonic metal band", "mbid": "3b0e8f01-3fd9-4104-9532-1e4b526ce562", "name": "Delain", "sortName": "Delain", "url": "https://www.setlist.fm/setlists/delain-1bd6fd7c.html" }, { "disambiguation": "", "mbid": "0470ff3e-3354-4b2a-a46d-e3ea50bed60b", "name": "Delain feat. Rob van der Loo, Sander Zoer, Guus Eikens", "sortName": "Delain feat. Loo, Rob van der, Zoer, Sander, Eikens, Guus", "url": "https://www.setlist.fm/setlists/delain-feat-rob-van-der-loo-sander-zoer-guus-eikens-3bcdc0e4.html" } ], "itemsPerPage": 30, "page": 1, "total": 9, "type": "artists" } } ``` -------------------------------- ### POST /settings-apply request body Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example JSON request body for the POST /settings-apply endpoint, containing a settings dict and an update_active boolean. The settings dict includes api, metadata, download, logging, and webui sections. ```json { "settings": { "api": { "musicbrainz": true, "genius": true, "genius_album_check": true, "deezer": true, "max_retry": 3 }, "metadata": { "lyrics": false, "copyright": true, "isrc": true, "genre": true, "album_artist": true, "multiple_artists": false, "artist_separator": "; ", "ffmpeg_metadata": false, "cover_art_file": false, "cover_art_size": "l", "lyrics_type": "plain", "synced_lyrics_metadata": true, "lrc_file": false, "lyrics_id3_synced_uslt_fallback": true, "lyrics_source": "youtube", "lyrics_fallback_source": "lrclib" }, "download": { "format": "mp3", "quality": 5, "id3_version": 3, "output_dir": "/home/chemgull/Documents/Coding/Python/SomeDL/downloads/downloads/", "output": "{album_artist}/{album_artist} - {song}", "number_downloaders": 1, "queue_size": 2, "sleep": 3, "cookies_path": "", "cookies_from_browser": "", "prefer_playlist": false, "fetch_albums": false, "check_if_file_exists": true, "download_archive": "", "sync_files": [ "/home/chemgull/.config/SomeDL/myPlaylist3_sync.json" ] }, "logging": { "log_level": 4, "download_report": 2 }, "webui": { "host": "127.0.0.1", "port": 5000, "browser": "chromium", "open_browser": false } }, "update_active": true } ``` -------------------------------- ### YouTube Search Success Response Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example of a 200 OK response for a YouTube search query. ```json { "result": { "description": null, "duration": null, "duration_seconds": 2855, "id": "OLAK5uy_nHqy1pH4pgb4_3ChdbJuLi4lQ_QyP2h38", "owned": false, "privacy": "PUBLIC", "related": [], "thumbnails": [], "title": "Moonbathers", "trackCount": 11, "tracks": [ { "album": { "id": "MPREb_NYSc5fVwzSO", "name": "Moonbathers" }, "artists": [ { "id": "UCPIXyGsEUrGIz7olJ1d7-Ig", "name": "Delain" } ], "communityVoteStatus": null, "creditsBrowseId": "MPTCDL4AzwmfqJY", "duration": "5:10", "duration_seconds": 310, "feedbackTokens": { "add": null, "remove": "AB9zfpIb1X5qDWjfQDvc3eBslX9rQYqUNxMxPUPAl2NgocQqtW9IWrWNXLKva8HLRipxggXxim4lL_5QJvadboa0hzAdvzp-Xw" }, "inLibrary": false, "isAvailable": true, "isExplicit": false, "likeStatus": "INDIFFERENT", "pinnedToListenAgain": false, "thumbnails": [ { "height": 60, "url": "https://yt3.googleusercontent.com/CxnYEyfnKAojje1sbDSsgFGatebvhiLrwwJ6EkXeIEZuARhxvOKs5LC7x639nVcurDH58mrWW1seXYkQ=w60-h60-l90-rj", "width": 60 }, { "height": 120, "url": "https://yt3.googleusercontent.com/CxnYEyfnKAojje1sbDSsgFGatebvhiLrwwJ6EkXeIEZuARhxvOKs5LC7x639nVcurDH58mrWW1seXYkQ=w120-h120-l90-rj", "width": 120 } ], "title": "Hands of Gold (feat. Alissa White-Gluz)", "videoId": "DL4AzwmfqJY", "videoType": "MUSIC_VIDEO_TYPE_ATV", "views": null } ], "views": null } } ``` -------------------------------- ### GET /get-history Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Returns the download history of the current session, including successful, already downloaded, and failed items. ```APIDOC ## GET /get-history ### Description Returns the download history of the current session. ### Method GET ### Endpoint /get-history ### Response #### Success Response (200) - **metadata_success_list** (_dict_) - List of songs that were successfully downloaded - **already_downloaded_list** (_dict_) - List of songs that were already downloaded and thus skipped (path is null if song was skipped because it was in the queue twice) - **failed_list** (_int_) - List of songs that failed to download #### Response Example ``` { "metadata_success_list": [ { "album_art": [ { "height": 60, "url": "https://yt3.googleusercontent.com/S0y9a8Dv3SlLbxf0SAAfY4UmgHLHxto-77tyThyl0aQaFKVz8rrruDsdH72j_ibf6qJdGi2yh8r1rDfr=w60-h60-l90-rj", "width": 60 }, { "height": 120, "url": "https://yt3.googleusercontent.com/S0y9a8Dv3SlLbxf0SAAfY4UmgHLHxto-77tyThyl0aQaFKVz8rrruDsdH72j_ibf6qJdGi2yh8r1rDfr=w120-h120-l90-rj", "width": 120 } ] } ] } ``` ### Error Handling #### Status Codes - 200 OK – Shutdown successfully triggered - 500 Internal Server Error – Server error #### Response Headers - Content-Type – application/json ``` -------------------------------- ### JavaScript fetch request to /status Source: https://somedl.readthedocs.io/en/latest/_sources/code_documentation/flask.rst.txt Example request to the /status endpoint using JavaScript fetch. The response is parsed as JSON. ```javascript const res = await fetch("/status"); const data = await res.json(); ``` -------------------------------- ### POST /yt-search success response (filter = songs) Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example success response for a song search, returning a list of up to 20 items with metadata such as title, artists, duration, and thumbnails. ```json { "result": [ { "album": { "id": "MPREb_iUk3tvhGHje", "name": "We Are The Others" }, "artists": [ { "id": "UCPIXyGsEUrGIz7olJ1d7-Ig", "name": "Delain" } ], "category": "Songs", "duration": "3:18", "duration_seconds": 198, "inLibrary": false, "isExplicit": false, "pinnedToListenAgain": false, "resultType": "song", "thumbnails": [ { "height": 60, "url": "https://yt3.googleusercontent.com/uEzYLh0FvVEV07ifl2boE6il0gjb7UykMCeWDO6wCV6Mr9FwMx6k_uwYO2SDJLRAdxPmQthHpoWLVQA=w60-h60-l90-rj", "width": 60 }, { "height": 120, "url": "https://yt3.googleusercontent.com/uEzYLh0FvVEV07ifl2boE6il0gjb7UykMCeWDO6wCV6Mr9FwMx6k_uwYO2SDJLRAdxPmQthHpoWLVQA=w120-h120-l90-rj", "width": 120 } ], "title": "We Are the Others", "videoId": "kErCh2TwPlU", "videoType": "MUSIC_VIDEO_TYPE_ATV", "views": "1.8M", "year": null } ] } ``` -------------------------------- ### GET /get-queue Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Returns the current download queue and the active download item. Provides information about the actively downloading song and the list of pending items. ```APIDOC ## GET /get-queue ### Description Returns the current download queue and the active download item. ### Method GET ### Endpoint /get-queue ### Response #### Success Response (200) - **active** (_dict_) - Same as in `/status` request. - **queue** (_list_) - List of the items in queue. #### Response Example ``` { "active": { "17806688160307332000002": { "data": {}, "text": "2/0 Delain - We Are The Others (Radio Version)" } }, "queue": [ { "somedl_id": "17806703611854036000001", "text_query": "delain - the cold", "video_type": "Search query", "video_type_original": "Search query" }, { "album_id": "MPREb_fMsob6AXjNV", "album_name": "Ego", "artist_all_names": [ "The Warning" ], "artist_id": "UCmZbBc8qMj0v9Q6dC-kw4Xg", "artist_name": "The Warning", "lyrics_id": "MPLYt_fMsob6AXjNV-1", "original_url_id": "u-BMzP-RLd4", "somedl_id": "17806707385822792000001", "song_id": "u-BMzP-RLd4", "song_title": "Ego", "song_title_clean": "Ego", "video_type": "MUSIC_VIDEO_TYPE_ATV", "video_type_original": "MUSIC_VIDEO_TYPE_ATV", "yt_url": "https://www.youtube.com/watch?v=u-BMzP-RLd4" } ] } ``` ### Error Handling #### Status Codes - 200 OK – Success - 500 Internal Server Error – Server error #### Response Headers - Content-Type – application/json ``` -------------------------------- ### POST /yt-get-album Request Body Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example request body for the POST /yt-get-album endpoint. Requires an album_id string field. A 400 Bad Request is returned if album_id is missing. ```json { "album_id": "OLAK5uy_miCUHAHUPqc21dc-Vs7KTxbbqqzFCl68c", } ``` -------------------------------- ### CLI Help Command Source: https://somedl.readthedocs.io/en/latest/usage/general_usage.html Run the help flag to view available configuration options. ```bash somedl -h ``` -------------------------------- ### GET /get-downloader-state Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Gets the state of the downloader, indicating whether it is running or paused. ```APIDOC ## GET /get-downloader-state ### Description Gets state of downloader (running or paused). ### Method GET ### Endpoint /get-downloader-state ### Response #### Success Response (200) - **is_running** (bool) - True if downloader is running, false if it is paused. #### Response Example { "is_running": true } ### Error Handling - 200 OK – Shutdown successfully triggered ``` -------------------------------- ### GET /clear-download-history Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Clears download history. ```APIDOC ## GET /clear-download-history ### Description Clears download history. ### Method GET ### Endpoint /clear-download-history ### Parameters None ### Response #### Success Response (200) Success #### Error Responses - **500 Internal Server Error** - Internal server error, failed to clear download history #### Response Headers - **Content-Type** - application/json ``` -------------------------------- ### Generate configuration file with somedl --generate-config Source: https://somedl.readthedocs.io/en/latest/_sources/usage/configuration.rst.txt Run this command to generate or regenerate the somedl_config.toml file with default configurations. The file is usually located at ~/.config/SomeDL/somedl_config.toml on Linux, C:\Users\\AppData\Roaming\SomeDL\somedl_config.toml on Windows, and ~/Library/Application Support/SomeDL/somedl_config.toml on MacOS. ```bash somedl --generate-config ``` -------------------------------- ### POST /add Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Requests the download of a list of search queries or URLs, similar to the CLI. It expands the input using generateSongList() and adds each song to the download queue. ```APIDOC ## POST /add ### Description Request to download a list of search queries or URLs, similar to the CLI. ### Method POST ### Endpoint /add ### Parameters #### Request Body - **input_list** (_list_ of _string_) - Required - List of search queries or URLs to download. ### Request Example ``` { "input_list": ["Artist - Title", "Artist - Title"] } ``` ### Behavior - Expands input using `generateSongList()` - Adds each song to `song_list_queue` for download ### Response #### Success Response (200) - **song_list** (_list_) - List of items to download, same as `queue` in `/get-queue`. #### Response Example ``` { "song_list": [ { "somedl_id": "17806724760830844000001", "text_query": "delain - not enough", "video_type": "Search query", "video_type_original": "Search query" }, { "album_id": "MPREb_B9YcEZY20ip", "album_name": "Dark Waters", "artist_all_names": [ "Delain" ], "artist_id": "UCPIXyGsEUrGIz7olJ1d7-Ig", "artist_name": "Delain", "lyrics_id": "MPLYt_B9YcEZY20ip-1", "original_url_id": "WOZOwTG9dmU", "somedl_id": "17806739333906158000001", "song_id": "WOZOwTG9dmU", "song_title": "Hideaway Paradise", "song_title_clean": "Hideaway Paradise", "video_type": "MUSIC_VIDEO_TYPE_ATV", "video_type_original": "MUSIC_VIDEO_TYPE_ATV", "yt_url": "https://www.youtube.com/watch?v=WOZOwTG9dmU" } ] } ``` #### Error Response (400) ``` { "error": "No item" } ``` #### Error Response (500) ``` { "error": "Failed to generate song list, internal server error" } ``` ### Error Handling #### Status Codes - 200 OK – Items successfully added to queue - 400 Bad Request – Missing or invalid “item” field - 500 Internal Server Error – Failed to generate song list, internal server error. #### Response Headers - Content-Type – application/json ``` -------------------------------- ### Search by query with CLI Source: https://somedl.readthedocs.io/en/latest/_sources/usage/general_usage.rst.txt Run a simple search by typing `somedl` followed by the query in quotes. ```bash somedl "Nirvana - Smells like teen spirit" ``` -------------------------------- ### GET /get-history Source: https://somedl.readthedocs.io/en/latest/_sources/code_documentation/flask.rst.txt Returns the download history of the current session. ```APIDOC ## GET /get-history ### Description Returns the download history of the current session. ### Method GET ### Endpoint /get-history ### Response #### Success Response (200) - **metadata_success_list** (list) - List of songs that were successfully downloaded. - **already_downloaded_list** (list) - List of songs that were already downloaded and thus skipped (path is null if song was skipped because it was in the queue twice). - **failed_list** (list) - List of songs that failed to download. #### Response Example { "metadata_success_list": [ { "album_art": [ { "height": 60 } ] } ] } ``` -------------------------------- ### Interactive prompts for somedl new-template Source: https://somedl.readthedocs.io/en/latest/_sources/usage/howto.rst.txt Shows the interactive CLI prompts for the 'somedl new-template' command, which asks for source folder, destination folder, and new output template. It warns about beta status and recommends backing up files. ```text ============================= SomeDL - New output template ============================= Utility to automatically move/copy your current library to a new storage template. You can also sort songs downloaded with SomeDL from another folder into your music library. This tool assumes it is used on files with complete metadata, it does not change metadata. If you want to organize a library with incomplete metadata, use 'somedl import' instead. This tool is in beta! Always back up your files first, especially when using Move mode. If you want you can share your feedback on this tool (positive or negative) on: https://github.com/ChemistryGull/SomeDL/discussions 1/4 | Source folder | Your old music library folder, or the folder containing the files you want to sort into your library | Path > /home/USER/Music/Old_SomeDL_Folder/ 2/4 | Destination folder | Your new music library folder | Path > /home/USER/Music/SomeDL/ ``` -------------------------------- ### POST /yt-get-album-browse-id Request Body Source: https://somedl.readthedocs.io/en/latest/code_documentation/flask.html Example request body for looking up an album by its browse ID. ```json { "album_id": "UCPdbkw3S_0ZSHAqlnxo9E_g", "return_album_data": "true" } ``` -------------------------------- ### Create a new sync file Source: https://somedl.readthedocs.io/en/latest/_sources/usage/howto.rst.txt Command to create a new sync file. The file is stored in the same directory as the config file and can be moved anywhere. ```bash somedl sync --new-sync-file <"name for new sync file"> ``` -------------------------------- ### POST /yt-get-album Source: https://somedl.readthedocs.io/en/latest/_sources/code_documentation/flask.rst.txt Retrieve detailed information about a specific album. The endpoint is documented but no parameters or response examples are provided in the source. ```APIDOC ## POST /yt-get-album ### Description Retrieve detailed information about a specific album. The endpoint is documented but no parameters or response examples are provided in the source. ### Method POST ### Endpoint /yt-get-album ```