api

Module for handling API requests.

check_update()

Check for update.

Returns

• returns True if there is an update.

Source code in spotdl/web/api.py

@router.get("/api/check_update")
def check_update() -> bool:
    """
    Check for update.

    ### Returns
    - returns True if there is an update.
    """

    try:
        _, ahead, _ = get_status(__version__, "master")
        if ahead > 0:
            return True
    except RuntimeError:
        latest_version = get_latest_version()
        latest_tuple = tuple(latest_version.replace("v", "").split("."))
        current_tuple = tuple(__version__.split("."))
        if latest_tuple > current_tuple:
            return True
    except RateLimitError:
        return False

    return False

connect_endpoint(client_id) async

Websocket endpoint.

Arguments

• websocket: The WebSocket instance.

Source code in spotdl/web/api.py

@router.get("/api/connect")
async def connect_endpoint(client_id: str):
    """
    Websocket endpoint.

    ### Arguments
    - websocket: The WebSocket instance.
    """

    if not CLIENT_ID_REGEX.match(client_id):
        raise HTTPException(status_code=400, detail="Invalid client_id.")

    await Client(client_id).connect()

download_file(file, client=Depends(get_client), state=Depends(get_current_state)) async

Download file using path.

Arguments

• file: The file path.
• client: The client's state.

Returns

• returns the file response, filename specified to return as attachment.

Source code in spotdl/web/api.py

@router.get("/api/download/file")
async def download_file(
    file: str,
    client: Client = Depends(get_client),
    state: ApplicationState = Depends(get_current_state),
):
    """
    Download file using path.

    ### Arguments
    - file: The file path.
    - client: The client's state.

    ### Returns
    - returns the file response, filename specified to return as attachment.
    """

    if state.web_settings.get("web_use_output_dir", False):
        # Use the static part of the server's output template, if it ends
        # partway through a file name, use the directory that file would be in
        output_prefix = state.downloader_settings["output"].split("{", 1)[0]
        expected_dir = Path(output_prefix)
        if not output_prefix.endswith(("/", os.sep)):
            expected_dir = expected_dir.parent
    else:
        expected_dir = get_spotdl_path() / f"web/sessions/{client.client_id}"

    # Resolve both paths so ".." segments and symlinks can't escape the directory
    file_path = Path(file).resolve()
    if (file_path.suffix[1:] not in FFMPEG_FORMATS) or (
        not file_path.is_relative_to(expected_dir.resolve())
    ):
        raise HTTPException(status_code=400, detail="Invalid download path.")

    return FileResponse(
        file_path,
        filename=file_path.name,
    )

download_url(url, client=Depends(get_client), state=Depends(get_current_state)) async

Download songs using Song url.

Arguments

• url: The url to download.

Returns

• returns the file path if the song was downloaded.

Source code in spotdl/web/api.py

@router.post("/api/download/url")
async def download_url(
    url: str,
    client: Client = Depends(get_client),
    state: ApplicationState = Depends(get_current_state),
) -> Optional[str]:
    """
    Download songs using Song url.

    ### Arguments
    - url: The url to download.

    ### Returns
    - returns the file path if the song was downloaded.
    """

    # Use the server's output setting, clients can't choose where files go
    if state.web_settings.get("web_use_output_dir", False):
        client.downloader.settings["output"] = state.downloader_settings["output"]
    else:
        client.downloader.settings["output"] = str(
            (get_spotdl_path() / f"web/sessions/{client.client_id}").absolute()
        )

    try:
        # Fetch song metadata
        song = Song.from_url(url)

        # Download Song
        _, path = await client.downloader.pool_download(song)

        if path is None:
            state.logger.error(f"Failure downloading {song.name}")

            raise HTTPException(
                status_code=500, detail=f"Error downloading: {song.name}"
            )

        return str(path.absolute())

    except Exception as exception:
        state.logger.error(f"Error downloading! {exception}")

        raise HTTPException(
            status_code=500, detail=f"Error downloading: {exception}"
        ) from exception

get_options()

Get options model (possible settings).

Returns

• returns the options.

Source code in spotdl/web/api.py

@router.get("/api/options_model")
def get_options() -> Dict[str, Any]:
    """
    Get options model (possible settings).

    ### Returns
    - returns the options.
    """

    parser = create_parser()

    options = {}
    for action in parser._actions:  # pylint: disable=protected-access
        if action.dest not in WEB_EDITABLE_SETTINGS:
            continue

        default = app_state.downloader_settings.get(action.dest, None)
        choices = list(action.choices) if action.choices else None

        type_name = ""
        if action.type is not None:
            if hasattr(action.type, "__objclass__"):
                type_name: str = action.type.__objclass__.__name__  # type: ignore
            else:
                type_name: str = action.type.__name__  # type: ignore

        if isinstance(
            action,
            argparse._StoreConstAction,  # pylint: disable=protected-access
        ):
            type_name = "bool"

        if choices is not None and action.nargs == "*":
            type_name = "list"

        options[action.dest] = {
            "type": type_name,
            "choices": choices,
            "default": default,
            "help": action.help,
        }

    return options

get_settings(client=Depends(get_client))

Get client settings.

Arguments

• client: The client's state.

Returns

• returns the settings.

Source code in spotdl/web/api.py

@router.get("/api/settings")
def get_settings(
    client: Client = Depends(get_client),
) -> DownloaderOptions:
    """
    Get client settings.

    ### Arguments
    - client: The client's state.

    ### Returns
    - returns the settings.
    """

    return client.downloader_settings

query_search(query)

Parse search term and return list of Song objects.

Arguments

• query: The query to parse.

Returns

• returns a list of Song objects.

Source code in spotdl/web/api.py

@router.get("/api/songs/search", response_model=None)
def query_search(query: str) -> List[Song]:
    """
    Parse search term and return list of Song objects.

    ### Arguments
    - query: The query to parse.

    ### Returns
    - returns a list of Song objects.
    """

    return get_search_results(query)

shutdown_event() async

Called when the server is shutting down.

Source code in spotdl/web/api.py

@router.on_event("shutdown")
async def shutdown_event():
    """
    Called when the server is shutting down.
    """

    if (
        not app_state.web_settings["keep_sessions"]
        and not app_state.web_settings["web_use_output_dir"]
    ):
        app_state.logger.info("Removing sessions directories")
        sessions_dir = Path(get_spotdl_path(), "web/sessions")
        if sessions_dir.exists():
            shutil.rmtree(sessions_dir)

songs_from_url(url)

Search for a song, playlist, artist or album on spotify using url.

Arguments

• url: The url to search.

Returns

• returns a list with Song objects to be downloaded.

Source code in spotdl/web/api.py

@router.get("/api/url", response_model=None)
def songs_from_url(url: str) -> List[Song]:
    """
    Search for a song, playlist, artist or album on spotify using url.

    ### Arguments
    - url: The url to search.

    ### Returns
    - returns a list with Song objects to be downloaded.
    """

    if "playlist" in url:
        playlist = Playlist.from_url(url)
        return list(map(Song.from_url, playlist.urls))
    if "album" in url:
        album = Album.from_url(url)
        return list(map(Song.from_url, album.urls))
    if "artist" in url:
        artist = Artist.from_url(url)
        return list(map(Song.from_url, artist.urls))

    return [Song.from_url(url)]

update_settings(settings, client=Depends(get_client))

Update client settings, and re-initialize downloader.

Arguments

• settings: The settings to change.
• client: The client's state.

Returns

• returns the new settings.

Source code in spotdl/web/api.py

@router.post("/api/settings/update")
def update_settings(
    settings: DownloaderOptionalOptions,
    client: Client = Depends(get_client),
) -> DownloaderOptions:
    """
    Update client settings, and re-initialize downloader.

    ### Arguments
    - settings: The settings to change.
    - client: The client's state.

    ### Returns
    - returns the new settings.
    """

    try:
        return client.update_settings(settings)
    except ValueError as exception:
        raise HTTPException(status_code=400, detail=str(exception)) from exception

version()

Get the current version This method is created to ensure backward compatibility of the web app, as the web app is updated with the latest regardless of the backend version

Returns

• returns the version of the app

Source code in spotdl/web/api.py

@router.get("/api/version", response_model=None)
def version() -> str:
    """
    Get the current version
    This method is created to ensure backward compatibility of the web app,
    as the web app is updated with the latest regardless of the backend version

    ### Returns
    -  returns the version of the app
    """

    return __version__