### BasicDownloadable Initialization and Usage Example

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/downloadable.md

Provides an example of creating and using the BasicDownloadable class for downloading any HTTP stream. It shows how to initialize the downloader and then get the size and download the file.

```python
import aiohttp
from streamrip.client import BasicDownloadable

async with aiohttp.ClientSession() as session:
    downloadable = BasicDownloadable(
        session=session,
        url="https://example.com/track.flac",
        extension="flac",
        source="custom"
    )
    
    size = await downloadable.size()
    await downloadable.download("output.flac", lambda x: print(f"{x} bytes"))
```

--------------------------------

### Basic and Tidal Download Example

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/downloadable.md

Demonstrates how to use BasicDownloadable for general file downloads and TidalDownloadable for downloading Tidal streams with MQA codec and encryption keys. Includes examples for getting file size and downloading with a progress callback.

```python
import aiohttp
from streamrip.client import BasicDownloadable, TidalDownloadable

async def download_track():
    async with aiohttp.ClientSession() as session:
        # Basic download
        basic = BasicDownloadable(
            session=session,
            url="https://example.com/track.flac",
            extension="flac",
            source="example"
        )
        
        size = await basic.size()
        print(f"File size: {size} bytes")
        
        await basic.download("track.flac", lambda x: print(f"+{x} bytes"))
        
        # Tidal download with MQA
        tidal = TidalDownloadable(
            session=session,
            url="https://tidal.com/stream/token",
            codec="mqa",
            encryption_key="base64_encoded_key",
            restrictions=[]
        )
        
        await tidal.download("tidal_track.flac", print)
```

--------------------------------

### Audio Conversion Usage Example

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/converter.md

Demonstrates two methods for audio conversion: direct class usage with specific parameters and using the `get` function with a `ConversionConfig` object. This example covers setting sampling rate, bit depth, and other conversion options.

```python
import asyncio
from streamrip.converter import get, FLAC
from streamrip.config import ConversionConfig

async def convert_audio():
    # Method 1: Direct class usage
    flac_converter = FLAC(
        filename="downloaded_track.m4a",
        sampling_rate=48000,
        bit_depth=16,
        copy_art=True,
        remove_source=True
    )
    await flac_converter.convert()
    print(f"Converted to: {flac_converter.final_fn}")
    
    # Method 2: Using get() function with config
    config = ConversionConfig(
        enabled=True,
        codec="MP3",
        sampling_rate=48000,
        bit_depth=16,
        lossy_bitrate=320
    )
    
    ConverterClass = get(config.codec)
    converter = ConverterClass(
        filename="another_track.flac",
        sampling_rate=config.sampling_rate,
        bit_depth=config.bit_depth,
        remove_source=True
    )
    await converter.convert()

asyncio.run(convert_audio())
```

--------------------------------

### Client Usage Example

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/clients.md

Demonstrates how to use a Streamrip client (e.g., QobuzClient) to get track metadata and downloadable stream information.

```APIDOC
## Client Usage Example

### Description
This example shows the general workflow for using a Streamrip client, including authentication, retrieving track metadata, and obtaining a downloadable stream URL.

### Methods
* `login()`: Authenticates the client.
* `get_metadata(track_id, item_type)`: Retrieves metadata for a given track ID and item type.
* `get_downloadable(track_id, quality)`: Gets a downloadable stream for a track ID and desired quality level.

### Example Usage
```python
from streamrip.config import Config
from streamrip.client import QobuzClient
import asyncio

async def get_track_metadata():
    config = Config("/path/to/config.toml")
    client = QobuzClient(config)
    
    # Authenticate
    await client.login()
    
    # Get metadata for a track
    track_id = "123456"
    metadata = await client.get_metadata(track_id, "track")
    print(metadata)
    
    # Get downloadable stream
    quality = 3
    downloadable = await client.get_downloadable(track_id, quality)
    print(f"URL: {downloadable.url}")
    print(f"Format: {downloadable.extension}")
    
    # Close session
    await client.session.close()

asyncio.run(get_track_metadata())
```
```

--------------------------------

### Qobuz Client Initialization and Login

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/clients.md

Example of how to instantiate and log in to the Qobuz client. Requires a Config object.

```python
client = QobuzClient(config)
await client.login()
```

--------------------------------

### Complete Streamrip Configuration Example

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/configuration.md

A comprehensive TOML configuration file example for Streamrip, covering settings for various music services, downloads, file paths, artwork, metadata, and CLI behavior.

```toml
[misc]
version = "2.2.0"
check_for_updates = true

[qobuz]
use_auth_token = false
email_or_userid = "your.email@example.com"
password_or_token = ""
app_id = ""
quality = 3
download_booklets = false
secrets = []

[tidal]
user_id = ""
country_code = "US"
access_token = ""
refresh_token = ""
token_expiry = ""
quality = 2
download_videos = false

[deezer]
arl = ""
quality = 2
lower_quality_if_not_available = true
use_deezloader = true
deezloader_warnings = true

[soundcloud]
client_id = ""
app_version = ""
quality = 0

[downloads]
folder = "~/StreamripDownloads"
source_subdirectories = true
disc_subdirectories = true
concurrency = true
max_connections = 6
requests_per_minute = 60
verify_ssl = true

[filepaths]
add_singles_to_folder = false
folder_format = "{albumartist}/{title} ({year})"
track_format = "{tracknumber:02d} {title}"
restrict_characters = true
truncate_to = 120

[conversion]
enabled = false
codec = "FLAC"
sampling_rate = 48000
bit_depth = 16
lossy_bitrate = 320

[artwork]
embed = true
embed_size = "large"
embed_max_width = 999999
save_artwork = true
saved_max_width = 999999

[metadata]
set_playlist_to_album = false
renumber_playlist_tracks = false
exclude = []

[database]
downloads_enabled = true
downloads_path = "~/.config/streamrip/downloads.db"
failed_downloads_enabled = true
failed_downloads_path = "~/.config/streamrip/failed_downloads.db"

[cli]
text_output = true
progress_bars = true
max_search_results = 100

[lastfm]
source = "qobuz"
fallback_source = ""

[qobuz_filters]
extras = true
repeats = true
non_albums = false
features = false
non_studio_albums = false
non_remaster = false

```

--------------------------------

### Install Python 3 and StreamRIP

Source: https://github.com/nathom/streamrip/wiki/Installing-on-Apple-Silicon-Macs

Installs Python 3 using Homebrew in the x86_64 architecture and then installs or upgrades StreamRIP using pip.

```bash
arch -x86_64 'brew install python3'
pip3 install streamrip --upgrade
rip --version
```

--------------------------------

### Install Streamrip using Homebrew

Source: https://github.com/nathom/streamrip/blob/dev/README.md

Install Streamrip on macOS or Linux systems with Homebrew.

```bash
brew install streamrip
```

--------------------------------

### Download Album Example

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/media.md

Demonstrates how to create a PendingAlbum, resolve its metadata, and initiate the download pipeline. Ensure to close the client session afterward.

```python
from streamrip.config import Config
from streamrip.client import QobuzClient
from streamrip.media import PendingAlbum
from streamrip.db import Database
import asyncio

async def download_album():
    config = Config("/path/to/config.toml")
    client = QobuzClient(config)
    await client.login()
    
    db = Database(...)
    
    # Create pending album
    pending = PendingAlbum(
        id="album_id",
        client=client,
        config=config,
        db=db
    )
    
    # Resolve to Album with metadata
    album = await pending.resolve()
    if album:
        # Execute full download pipeline
        await album.rip()
    
    await client.session.close()

asyncio.run(download_album())
```

--------------------------------

### Install Streamrip from AUR (Arch Linux)

Source: https://github.com/nathom/streamrip/blob/dev/README.md

Install Streamrip on Arch Linux using the AUR. Ensure required packages are installed first.

```bash
git clone https://aur.archlinux.org/streamrip.git
cd streamrip
makepkg -si
```

--------------------------------

### Deezer Client Initialization and Login

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/clients.md

Example of how to instantiate and log in to the Deezer client. Requires a Config object.

```python
client = DeezerClient(config)
await client.login()
```

--------------------------------

### Tidal Client Initialization and Login

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/clients.md

Example of how to instantiate and log in to the Tidal client. Requires a Config object.

```python
client = TidalClient(config)
await client.login()
```

--------------------------------

### Full Usage Example: Download Album

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/main.md

This example demonstrates how to use the Streamrip library to download an album. It includes setting up configuration, using the Main class as an async context manager, adding a URL, resolving it, and initiating the rip process.

```python
from streamrip.config import Config
from streamrip.rip.main import Main
import asyncio

async def download_album():
    config = Config("/path/to/config.toml")
    async with Main(config) as main:
        await main.add("https://www.qobuz.com/us-en/album/rumours-fleetwood-mac/0603497941032")
        await main.resolve()
        await main.rip()

asyncio.run(download_album())
```

--------------------------------

### Search and Download Album (Async)

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/README.md

This example demonstrates how to search for an album interactively and then proceed with downloading. It requires the configuration file to be in place.

```python
async def search_and_download():
    config = Config("~/.config/streamrip/config.toml")
    
    async with Main(config) as main:
        # Interactive search
        await main.search_interactive("qobuz", "album", "fleetwood mac")
        
        # Metadata and download
        await main.resolve()
        await main.rip()

asyncio.run(search_and_download())
```

--------------------------------

### Example Filepath Formats for Flat Structure

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/configuration.md

Configure folder and track naming conventions for a flat file organization structure. This example simplifies naming for easier browsing.

```toml
# Flat structure
folder_format = "{albumartist} - {title} ({year})"
track_format = "{tracknumber:02d} {title}"

```

--------------------------------

### Full Client Usage Example (Qobuz)

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/clients.md

Demonstrates the complete workflow for using a client, specifically QobuzClient. This includes configuration, login, fetching track metadata, retrieving a downloadable stream URL, and closing the session.

```python
from streamrip.config import Config
from streamrip.client import QobuzClient
import asyncio

async def get_track_metadata():
    config = Config("/path/to/config.toml")
    client = QobuzClient(config)
    
    # Authenticate
    await client.login()
    
    # Get metadata for a track
    track_id = "123456"
    metadata = await client.get_metadata(track_id, "track")
    print(metadata)
    
    # Get downloadable stream
    quality = 3
    downloadable = await client.get_downloadable(track_id, quality)
    print(f"URL: {downloadable.url}")
    print(f"Format: {downloadable.extension}")
    
    # Close session
    await client.session.close()

asyncio.run(get_track_metadata())
```

--------------------------------

### Initialize Database Classes

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/database.md

Demonstrates how to initialize `Downloads` and `Failed` database instances and combine them into a main `Database` object. This setup is required before performing any database operations.

```python
from streamrip.db import Database, Downloads, Failed

# Create database instance
downloads_db = Downloads("/path/to/downloads.db")
failed_db = Failed("/path/to/failed.db")
database = Database(downloads_db, failed_db)
```

--------------------------------

### Check Homebrew Version

Source: https://github.com/nathom/streamrip/wiki/Home

Verify that Homebrew has been installed successfully by checking its version. This output indicates a successful installation.

```bash
brew --version
```

--------------------------------

### Example Filepath Formats for Genre Organization

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/configuration.md

Configure folder and track naming conventions for organizing music by genre. This example uses a 'Music/{genre}/{albumartist}' structure.

```toml
# Organized by genre
folder_format = "Music/{albumartist}/{title}"
track_format = "{tracknumber} {artist} - {title}"

```

--------------------------------

### Example Filepath Formats for Classical Music

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/configuration.md

Configure folder and track naming conventions for classical music, including disc folders and composer information. This example demonstrates a specific structure for organizing classical releases.

```toml
# Classical music with disc folders
folder_format = "{albumartist}/[{year}] {title}"
track_format = "{discnumber}-{tracknumber:02d} {composer} - {title}"

```

--------------------------------

### Install Streamrip from development branch

Source: https://github.com/nathom/streamrip/blob/dev/README.md

Install Streamrip directly from the development branch for the latest features. Use this if you encounter issues or want bleeding-edge functionality.

```bash
pip3 install git+https://github.com/nathom/streamrip.git@dev
```

--------------------------------

### Get General Help

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/cli-commands.md

Displays general help information for the Streamrip CLI.

```bash
rip --help
```

--------------------------------

### Download MP3 Track via Search

Source: https://github.com/nathom/streamrip/wiki/Command-Line-Reference

Example showing how to search for a track and download it as a 320kbps MP3.

```bash
rip -q 2 -c MP3 search deezer track "Dance Song" # 320kbps MP3
```

--------------------------------

### Check Streamrip Installation

Source: https://github.com/nathom/streamrip/wiki/Home

Verify that Streamrip has been installed successfully by checking its version. This command should output the installed Rip version.

```bash
rip --version
```

--------------------------------

### Install Streamrip using pip3

Source: https://github.com/nathom/streamrip/wiki/Home

Install the Streamrip package using pip3, the Python package manager. This command should be run after Python is installed and accessible.

```bash
pip3 install streamrip
```

--------------------------------

### Install Rosetta 2

Source: https://github.com/nathom/streamrip/wiki/Installing-on-Apple-Silicon-Macs

Ensures Rosetta 2 is installed, which is necessary for running x86_64 applications on Apple Silicon.

```bash
softwareupdate --install-rosetta
```

--------------------------------

### Check FFmpeg Installation

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/converter.md

Verify that FFmpeg is installed and accessible in your system's PATH by running this command in your terminal.

```bash
ffmpeg -version
```

--------------------------------

### Downloadable Download Method Example

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/downloadable.md

Demonstrates how to download an audio stream to a specified file path using a progress callback. The callback function is invoked after each chunk is downloaded.

```python
def progress_callback(bytes_written: int):
    print(f"Downloaded {bytes_written} bytes")

await downloadable.download("track.flac", progress_callback)
```

--------------------------------

### Install Streamrip using Paru (Arch Linux)

Source: https://github.com/nathom/streamrip/blob/dev/README.md

Install Streamrip on Arch Linux using the Paru AUR helper. This command automates dependency resolution.

```bash
paru -S streamrip
```

--------------------------------

### Qobuz Service Configuration Example

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/configuration.md

This TOML snippet shows the configuration parameters for the Qobuz streaming service. It includes settings for authentication, audio quality, and booklet downloads.

```toml
[qobuz]
use_auth_token = false
email_or_userid = ""
password_or_token = ""
app_id = ""
quality = 3
download_booklets = false
secrets = []
```

--------------------------------

### Download Best Quality FLAC

Source: https://github.com/nathom/streamrip/wiki/Command-Line-Reference

Example demonstrating how to download an album in the best available quality and convert it to FLAC format.

```bash
rip -q 4 -c FLAC url https://tidal.com/album/123  # Best quality FLAC
```

--------------------------------

### Check Python 3 Version

Source: https://github.com/nathom/streamrip/wiki/Home

Verify that Python 3 has been installed correctly by checking its version. The output should display the installed Python version.

```bash
python3 --version
```

--------------------------------

### Convert Audio File Example

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/converter.md

Demonstrates how to use the FLAC converter to convert an audio file and print the output filename. Ensure the FLAC class is imported.

```python
from streamrip.converter import FLAC

converter = FLAC(
    filename="original.m4a",
    sampling_rate=48000,
    bit_depth=16,
    remove_source=True
)
await converter.convert()
print(f"Converted to: {converter.final_fn}")
```

--------------------------------

### Asynchronous Download Tracking

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/database.md

An asynchronous example demonstrating how to use the `Database` class to track downloads. It includes checking if an item is already downloaded, marking it as downloaded on success, or marking it as failed if an error occurs.

```python
import asyncio
from streamrip.db import Database, Downloads, Failed

async def main():
    # Initialize databases
    downloads_db = Downloads("/path/to/downloads.db")
    failed_db = Failed("/path/to/failed.db")
    database = Database(downloads_db, failed_db)
    
    # Check if item was already downloaded
    track_id = "12345"
    if database.downloaded(track_id):
        print(f"Track {track_id} already downloaded")
        return
    
    # Simulate download process
    try:
        # ... download logic ...
        database.set_downloaded(track_id)
        print(f"Successfully downloaded {track_id}")
    except Exception as e:
        database.set_failed("qobuz", "track", track_id)
        print(f"Failed to download {track_id}: {e}")
    
    # View statistics
    total_downloads = len(downloads_db.all())
    total_failed = len(failed_db.all())
    print(f"Downloaded: {total_downloads}, Failed: {total_failed}")

asyncio.run(main())
```

--------------------------------

### Get Help for Config Group

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/cli-commands.md

Displays help information for the 'config' command group in Streamrip.

```bash
rip config --help
```

--------------------------------

### Install Homebrew on macOS

Source: https://github.com/nathom/streamrip/wiki/Home

Use this command to install the Homebrew package manager on macOS. You will need administrator access.

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

--------------------------------

### Example Metadata Exclusion Configuration

Source: https://github.com/nathom/streamrip/wiki/Metadata-Tag-Names

Demonstrates how to exclude specific metadata tags like 'genre' and 'albumartist' in `config.toml`.

```toml
[metadata]
# The following metadata tags won't be applied
exclude = ["genre", "albumartist"]
```

--------------------------------

### Get Help for Search Command

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/cli-commands.md

Displays help information specific to the 'search' command in Streamrip.

```bash
rip search --help
```

--------------------------------

### Deezer Service Configuration Example

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/configuration.md

This TOML snippet demonstrates the configuration settings for the Deezer streaming service. Key parameters include the ARL cookie, audio quality, and options for using deezloader.

```toml
[deezer]
arl = ""
quality = 2
lower_quality_if_not_available = true
use_deezloader = true
deezloader_warnings = true
```

--------------------------------

### Downloadable Size Method Example

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/downloadable.md

Shows how to retrieve the total file size of a stream in bytes using an HTTP HEAD request. This is useful for displaying download progress or estimating download time.

```python
total_bytes = await downloadable.size()
print(f"Downloading {total_bytes / 1024 / 1024:.2f} MB")
```

--------------------------------

### Configure Audio Conversion Settings

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/configuration.md

Enable or disable audio format conversion and specify target codec, sampling rate, bit depth, and bitrate. Requires FFmpeg to be installed.

```toml
[conversion]
enabled = false
codec = "FLAC"
sampling_rate = 48000
bit_depth = 16
lossy_bitrate = 320
```

--------------------------------

### Debug SSL Issues

Source: https://github.com/nathom/streamrip/wiki/Command-Line-Reference

Example for debugging potential SSL verification problems by disabling SSL verification during a URL download.

```bash
rip -v --no-ssl-verify url https://problematic.url  # Debug SSL issues
```

--------------------------------

### Initialize and Login SoundcloudClient

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/clients.md

Shows how to initialize a SoundcloudClient with a configuration and then log in.

```python
client = SoundcloudClient(config)
await client.login()
```

--------------------------------

### Tidal Service Configuration Example

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/configuration.md

This TOML snippet outlines the configuration options for the Tidal streaming service. It covers user ID, country code, access tokens, and quality settings.

```toml
[tidal]
user_id = ""
country_code = "US"
access_token = ""
refresh_token = ""
token_expiry = ""
quality = 2
download_videos = false
```

--------------------------------

### Custom FFmpeg Arguments for Compression

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/converter.md

Apply custom FFmpeg arguments during conversion, such as setting a specific compression level. This example uses `-compression_level 12` for maximum compression.

```python
from streamrip.converter import FLAC

# Use custom FFmpeg compression level
converter = FLAC(
    filename="track.m4a",
    ffmpeg_arg="-compression_level 12"  # Maximum compression
)
await converter.convert()
```

--------------------------------

### Downloads.__init__()

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/database.md

Initializes the Downloads database.

```APIDOC
## Class: Downloads

**Import:** `streamrip.db.Downloads`

Database for tracking successfully downloaded items.

```python
class Downloads(DatabaseBase):
    structure = {"id": ["text", "primary", "key"]}
    name = "downloads"
    
    def __init__(self, path: str)
```

### Constructor Parameters

#### Parameters
- **path** (str) - Path to downloads.db file
```

--------------------------------

### Install Python 3 using Homebrew

Source: https://github.com/nathom/streamrip/wiki/Home

Install Python 3 on macOS using the Homebrew package manager. This command should be run after Homebrew is installed.

```bash
brew install python3
```

--------------------------------

### Initialize and Modify Config

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/config.md

Demonstrates how to initialize the Config object with a TOML file path and modify a specific setting, then save the changes to disk.

```python
config = Config("/path/to/config.toml")
config.file.qobuz.quality = 4
config.save_file()
```

--------------------------------

### Check Python Version on Windows

Source: https://github.com/nathom/streamrip/wiki/Home

Verify Python installation on Windows. Depending on the installation, you might use 'python' or 'python3'.

```bash
python --version
```

```bash
python3 --version
```

--------------------------------

### Initialize Qobuz Client

Source: https://github.com/nathom/streamrip/wiki/Scripting-with-Streamrip-v2

Initializes the Qobuz client with default configuration and user credentials. Ensure to replace 'YOUR_EMAIL' and 'YOUR_PASSWORD' with actual values.

```python
from streamrip.client import QobuzClient
from streamrip.config import Config

config = Config.defaults()
config.session.qobuz.email_or_userid = "YOUR_EMAIL"
config.session.qobuz.password_or_token = "YOUR_PASSWORD"
c = QobuzClient(config)
```

--------------------------------

### Download from File with Overrides

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/cli-commands.md

Demonstrates using the 'file' command in conjunction with quality and codec override options.

```bash
rip -q 3 --codec flac file playlists.txt
```

--------------------------------

### Get Converter Class by Codec Name

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/converter.md

Use the `get` function to retrieve the appropriate Converter class for a given codec name. This returns the class itself, not an instance, which can then be used to create a converter object.

```python
from streamrip.converter import get

codec = "FLAC"
ConverterClass = get(codec)
converter = ConverterClass("track.m4a")
await converter.convert()
```

--------------------------------

### SearchResults.preview

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/metadata.md

Gets a formatted preview of a search result at a specified index.

```APIDOC
## SearchResults.preview(index: int)

### Description
Get a formatted preview of a result at the given index.

### Method
`SearchResults.preview`

### Parameters
#### Path Parameters
- **index** (int) - Required - Result index

### Response
#### Success Response
- **Formatted preview string** - A string representing the formatted preview.
```

--------------------------------

### Import Client and Downloadable Classes

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/README.md

Import various client classes for different streaming services (Qobuz, Tidal, Deezer, Soundcloud) along with base and specific downloadable classes.

```python
from streamrip.client import Client, QobuzClient, TidalClient, DeezerClient, SoundcloudClient
from streamrip.client import Downloadable, BasicDownloadable
```

--------------------------------

### Get Album Metadata

Source: https://github.com/nathom/streamrip/wiki/Scripting-with-Streamrip-v2

Retrieves metadata for a specific album using its ID. This is an asynchronous operation.

```python
my_album = await c.get_metadata("123456", "album")
print(my_album) # should print a giant dictionary with metadata
```

--------------------------------

### Failed.__init__()

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/database.md

Initializes the Failed database.

```APIDOC
## Class: Failed

**Import:** `streamrip.db.Failed`

Database for tracking items that failed to download.

```python
class Failed(DatabaseBase):
    structure = {
        "source": ["text"],
        "media_type": ["text"],
        "id": ["text", "primary", "key"]
    }
    name = "failed"
    
    def __init__(self, path: str)
```

### Constructor Parameters

#### Parameters
- **path** (str) - Path to failed_downloads.db file
```

--------------------------------

### Catch MissingCredentialsError

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/errors.md

Example of catching MissingCredentialsError when credentials are not found. This typically occurs if configuration files are missing or incomplete.

```python
from streamrip.exceptions import MissingCredentialsError

try:
    await main.get_logged_in_client("qobuz")
except MissingCredentialsError:
    print("Please configure your Qobuz credentials in config.toml")
```

--------------------------------

### Database Configuration

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/config.md

Configure settings for download tracking databases, including enabling/disabling databases and specifying their paths.

```python
from dataclasses import dataclass

@dataclass
class DatabaseConfig:
    downloads_enabled: bool
    downloads_path: str
    failed_downloads_enabled: bool
    failed_downloads_path: str
```

--------------------------------

### SoundcloudClient Constructor

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/clients.md

Initializes the SoundcloudClient with application configuration.

```APIDOC
## SoundcloudClient Constructor

### Description
Initializes the SoundcloudClient with the provided application configuration.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Constructor Signature
```python
def __init__(self, config: Config)
```

### Parameters
* **config** (Config) - Required - Application configuration object

### Example
```python
client = SoundcloudClient(config)
await client.login()
```
```

--------------------------------

### Track.preprocess

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/media.md

Prepares for track download by creating the download folder and updating the progress display.

```APIDOC
## Track.preprocess

### Description
Create download folder and update progress display.

### Method
async

### Endpoint
None

### Parameters
None

### Request Example
```python
# Example usage within the Track class context
await self.preprocess()
```

### Response
#### Success Response (None)
None

#### Response Example
None
```

--------------------------------

### Catch InvalidAppSecretError

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/errors.md

Example of catching InvalidAppSecretError during Qobuz client login. This error is raised if the Qobuz app secret is missing or has been invalidated.

```python
from streamrip.exceptions import InvalidAppSecretError

try:
    await qobuz_client.login()
except InvalidAppSecretError:
    print("Invalid Qobuz app secret. Run 'rip config open' to reconfigure.")
```

--------------------------------

### Catch InvalidAppIdError

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/errors.md

Example of catching InvalidAppIdError during Qobuz client login. This error occurs if the Qobuz app ID is not configured or has been invalidated.

```python
from streamrip.exceptions import InvalidAppIdError

try:
    await qobuz_client.login()
except InvalidAppIdError:
    print("Invalid Qobuz app ID. Update streamrip or check config.")
```

--------------------------------

### SoundcloudClient Constructor

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/clients.md

Illustrates the constructor for the SoundcloudClient, which requires a Config object.

```python
def __init__(self, config: Config)
```

--------------------------------

### Download to Custom Folder from URL

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/cli-commands.md

Shows how to download content to a specified folder using the '-f' option.

```bash
rip -f ~/Music url https://www.qobuz.com/us-en/album/...
```

--------------------------------

### Silent Batch Processing

Source: https://github.com/nathom/streamrip/wiki/Command-Line-Reference

Example of performing a batch download from a file without displaying progress bars, suitable for automated tasks.

```bash
rip --no-progress -f file batch.txt  # Silent batch processing
```

--------------------------------

### Open Configuration in Vim

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/cli-commands.md

Opens the Streamrip configuration file specifically in Vim or Neovim.

```bash
rip config open --vim
```

--------------------------------

### Download with Verbose Logging

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/cli-commands.md

Downloads media from a Qobuz URL and enables verbose logging for debugging purposes.

```bash
rip -v url https://www.qobuz.com/us-en/album/...
```

--------------------------------

### Show Configuration File Path

Source: https://github.com/nathom/streamrip/wiki/Command-Line-Reference

Displays the current location of the Streamrip configuration file.

```bash
rip config path
```

--------------------------------

### Catch AuthenticationError

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/errors.md

Example of catching AuthenticationError during client login. Use this when authentication with a streaming service fails due to invalid credentials or tokens.

```python
from streamrip.exceptions import AuthenticationError
from streamrip.client import QobuzClient

try:
    client = QobuzClient(config)
    await client.login()
except AuthenticationError:
    print("Login failed: Check your credentials")
    # Prompt user for new credentials
```

--------------------------------

### Download Multiple Albums from URLs

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/cli-commands.md

Demonstrates downloading multiple albums from different services by providing multiple URLs.

```bash
rip url \
  https://www.qobuz.com/us-en/album/rumours-fleetwood-mac/0603497941032 \
  https://tidal.com/browse/album/147569387
```

--------------------------------

### Get Converter Class

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/converter.md

Retrieves a Converter class based on the codec name. This allows for dynamic instantiation of converters for various audio formats.

```APIDOC
## get(codec_name: str) -> type[Converter]

### Description
Get the Converter class for a codec name. This function is used to dynamically obtain the appropriate converter class for a given audio codec.

### Method
`get`

### Parameters
#### Path Parameters
- **codec_name** (str) - Required - Codec name: FLAC, ALAC, MP3, AAC, OPUS, or VORBIS

### Returns
Converter class (not an instance)

### Raises
- `ValueError`: If codec name is not supported

### Example
```python
from streamrip.converter import get

codec = "FLAC"
ConverterClass = get(codec)
converter = ConverterClass("track.m4a")
await converter.convert()
```
```

--------------------------------

### Basic Streamrip Command Syntax

Source: https://github.com/nathom/streamrip/wiki/Command-Line-Reference

Illustrates the fundamental structure for executing Streamrip commands, including global options, the command itself, and its arguments.

```bash
rip [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS] [ARGUMENTS]
```

--------------------------------

### Catch IneligibleError

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/errors.md

Example of catching IneligibleError when an account cannot stream a track due to restrictions. This can be due to subscription level, geographic limitations, or track blacklisting.

```python
from streamrip.exceptions import IneligibleError

try:
    downloadable = await client.get_downloadable(track_id, quality)
except IneligibleError:
    print(f"Your account is not eligible to stream track {track_id}")
```

--------------------------------

### Download from Text File of URLs

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/cli-commands.md

Use the 'file' command to download content listed in a plain text file, with one URL per line.

```bash
rip file urls.txt
```

--------------------------------

### Catch NonStreamableError During Metadata Fetch

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/errors.md

Example of catching NonStreamableError when fetching metadata for an item. It checks for a custom message or prints a generic one, then logs the failure.

```python
from streamrip.exceptions import NonStreamableError
from streamrip.client import Client

try:
    metadata = await client.get_metadata(item_id, "track")
except NonStreamableError as e:
    if e.message:
        print(f"Item not available: {e.message}")
    else:
        print(f"Item {item_id} is not streamable")
    # Record failure in database
    database.set_failed(source, "track", item_id)
```

--------------------------------

### Download from Direct URLs

Source: https://github.com/nathom/streamrip/wiki/Command-Line-Reference

Use the 'url' command to download content by providing one or more direct URLs to the desired media.

```bash
rip url https://qobuz.com/album/123
```

```bash
rip url https://tidal.com/track/456 https://deezer.com/album/789
```

--------------------------------

### Get Formatted Search Result Summaries

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/metadata.md

Retrieves a list of formatted strings, each representing a summary of a search result. Useful for displaying search results to the user.

```python
summaries = search_results.summaries()
```

--------------------------------

### Main.add

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/main.md

Adds a single URL to the pending items for download. It parses the URL to identify the source and media type, fetches necessary credentials, and creates a Pending object.

```APIDOC
## async add(url: str)

### Description
Add a single URL to the pending items. Parses the URL to determine source and media type, fetches credentials if needed, and creates a Pending object.

### Method
ASYNC

### Endpoint
N/A (Python method)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```python
async with Main(config) as main:
    await main.add("https://www.qobuz.com/us-en/album/rumours-fleetwood-mac/0603497941032")
```

### Response
#### Success Response
None (returns None)

#### Response Example
None
```

--------------------------------

### Get Authenticated Client

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/main.md

Retrieve an authenticated client for a streaming service. This function will prompt for credentials if the user is not already logged in. Ensure the source name is valid.

```python
client = await main.get_logged_in_client("qobuz")
```

--------------------------------

### Album.preprocess

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/media.md

Prepares for album download by displaying the album title in the progress output.

```APIDOC
## Album.preprocess

### Description
Display album title in progress output.

### Method
async

### Endpoint
None

### Parameters
None

### Request Example
```python
# Example usage within the Album class context
await self.preprocess()
```

### Response
#### Success Response (None)
None

#### Response Example
None
```

--------------------------------

### BasicDownloadable Constructor

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/downloadable.md

Initializes a BasicDownloadable instance, which is suitable for downloading audio from any standard HTTP URL without requiring service-specific logic.

```APIDOC
## BasicDownloadable

### Description
Simple downloader for any HTTP URL without service-specific handling.

### Constructor Parameters
#### Parameters
- **session** (aiohttp.ClientSession) - Required - HTTP session
- **url** (str) - Required - Stream URL
- **extension** (str) - Required - File extension
- **source** (str) - Optional - Service name (Defaults to "Unknown")

### Example
```python
import aiohttp
from streamrip.client import BasicDownloadable

async with aiohttp.ClientSession() as session:
    downloadable = BasicDownloadable(
        session=session,
        url="https://example.com/track.flac",
        extension="flac",
        source="custom"
    )
    
    size = await downloadable.size()
    await downloadable.download("output.flac", lambda x: print(f"{x} bytes"))
```
```

--------------------------------

### Main.add_all

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/main.md

Adds multiple URLs concurrently, which is more efficient than calling add() multiple times due to reused client connections.

```APIDOC
## async add_all(urls: list[str])

### Description
Add multiple URLs concurrently. More efficient than calling `add()` multiple times as it reuses client connections.

### Method
ASYNC

### Endpoint
N/A (Python method)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```python
await main.add_all([
    "https://www.qobuz.com/us-en/album/album1/id1",
    "https://tidal.com/browse/album/id2",
])
```

### Response
#### Success Response
None (returns None)

#### Response Example
None
```

--------------------------------

### QobuzClient Constructor

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/clients.md

Initializes the QobuzClient, which is a concrete implementation of the Client class for the Qobuz streaming service. Requires an application configuration object.

```APIDOC
## QobuzClient(config: Config)

### Description
Constructor for QobuzClient.

### Parameters
#### Path Parameters
- **config** (Config) - Required - Application configuration object.

### Example
```python
client = QobuzClient(config)
await client.login()
```
```

--------------------------------

### Get Formatted Search Result Preview

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/metadata.md

Generates a formatted preview string for a specific search result based on its index. Useful for showing a quick look at a result.

```python
preview = search_results.preview(index=0)
```

--------------------------------

### Downloadable.size

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/downloadable.md

Retrieves the total file size of the stream in bytes. This method performs an HTTP HEAD request to efficiently get the size without downloading the entire file.

```APIDOC
## async size() -> int

### Description
Get the total file size in bytes using HTTP HEAD request.

### Returns
- **int** - Total bytes to download

### Example
```python
total_bytes = await downloadable.size()
print(f"Downloading {total_bytes / 1024 / 1024:.2f} MB")
```
```

--------------------------------

### Displaying StreamRIP Help Information

Source: https://github.com/nathom/streamrip/wiki/Troubleshooting

Use these commands to view help documentation for various StreamRIP functionalities. Ensure the 'rip' executable is in your system's PATH.

```bash
rip --help
rip filter --help
rip search --help
rip discover --help
rip config --help
rip lastfm --help
```

--------------------------------

### Get Specific Search Result Items

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/metadata.md

Retrieves one or more Summary objects from the search results at the specified index or indices. Useful for accessing detailed information about selected results.

```python
selected_summaries = search_results.get_choices(indices=[0, 2])
```

--------------------------------

### Download from JSON File of URLs

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/cli-commands.md

Utilize the 'file' command with a JSON file containing source, media_type, and id for downloads.

```bash
rip file search_results.json
```

--------------------------------

### Get Genres as Comma-Separated String

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/metadata.md

The `get_genres` method of `AlbumMetadata` returns a single string containing all genre tags, separated by commas. This is useful for displaying or storing genres in a flattened format.

```python
Return genres as a comma-separated string.

    Returns:
        "Genre1, Genre2, Genre3"
```

--------------------------------

### Import Main Class for Orchestration

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/README.md

Import the Main class, which serves as the primary entry point for orchestrating download tasks within the Streamrip library.

```python
from streamrip.rip.main import Main
```

--------------------------------

### Open Streamrip configuration file

Source: https://github.com/nathom/streamrip/blob/dev/README.md

Open the Streamrip configuration file for editing. This allows for advanced customization of the downloader's behavior.

```bash
rip config open
```

--------------------------------

### Download with Specific Quality and URL

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/cli-commands.md

Combines the quality override option with downloading a specific album URL.

```bash
rip -q 4 url https://www.qobuz.com/us-en/album/rumours-fleetwood-mac/0603497941032
```

--------------------------------

### Import Core Streamrip Modules

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/README.md

Import essential modules for configuration, conversion, database operations, exceptions, media representation, and metadata handling.

```python
from streamrip import Config, converter, db, exceptions, media, metadata
```

--------------------------------

### Get Formatted Copyright String

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/metadata.md

The `get_copyright` method of `AlbumMetadata` returns the copyright string, ensuring that special Unicode characters for copyright (©) and phonogram (℗) are correctly included. It returns `None` if no copyright information is available.

```python
Return copyright string with special Unicode characters (© for copyright, ℗ for phonogram).

    Returns:
        Formatted copyright string or None
```

--------------------------------

### Dummy Database Implementation

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/database.md

Provides a mock implementation of DatabaseInterface that performs no operations. Use this when database tracking is disabled.

```python
from streamrip.db import Dummy

# Use dummy database to skip tracking
db = Dummy()
db.add(("track_123",))  # Does nothing
print(db.contains(id="track_123"))  # Always False
```

--------------------------------

### Create an aiohttp ClientSession

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/clients.md

Configures and returns an aiohttp ClientSession with custom headers and SSL verification options.

```python
aiohttp.ClientSession
```

--------------------------------

### Specify Configuration Path

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/cli-commands.md

Use this option to point Streamrip to a custom TOML configuration file instead of the default.

```bash
rip --config-path ~/.streamrip/custom.toml url https://...
```

--------------------------------

### Async Context Manager Entry

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/main.md

Async context manager entry point for the Main class. Used to set up resources for asynchronous operations.

```python
await main.__aenter__()
```

--------------------------------

### Verify Homebrew Architecture

Source: https://github.com/nathom/streamrip/wiki/Installing-on-Apple-Silicon-Macs

Confirms that Homebrew is running under the x86_64 architecture, essential for compatibility with Rosetta 2.

```bash
arch -x86_64 'brew --version'
```

--------------------------------

### Download album and convert to MP3

Source: https://github.com/nathom/streamrip/blob/dev/README.md

Download an album and convert the audio files to MP3 format using the --codec option.

```bash
rip --codec mp3 url https://open.qobuz.com/album/0060253780968
```

--------------------------------

### FLAC Conversion Usage

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/converter.md

Shows how to instantiate and use the FLAC converter for lossless audio conversion. The output file will have a .flac extension.

```python
from streamrip.converter import FLAC

flac = FLAC("track.m4a", sampling_rate=48000, bit_depth=16)
await flac.convert()
# Outputs: track.flac
```

--------------------------------

### Search and Download Album Interactively

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/cli-commands.md

Searches for an album on Qobuz and allows interactive selection for download.

```bash
rip search qobuz album "pink floyd"
```

--------------------------------

### Download multiple albums from Qobuz

Source: https://github.com/nathom/streamrip/blob/dev/README.md

Download multiple albums from Qobuz by providing multiple URLs.

```bash
rip url https://www.qobuz.com/us-en/album/back-in-black-ac-dc/0886444889841 https://www.qobuz.com/us-en/album/blue-train-john-coltrane/0060253764852
```

--------------------------------

### Conversion Configuration

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/config.md

Configure settings for audio file conversion using FFmpeg, specifying codec, sampling rate, bit depth, and bitrate.

```python
from dataclasses import dataclass

@dataclass
class ConversionConfig:
    enabled: bool
    codec: str
    sampling_rate: int
    bit_depth: int
    lossy_bitrate: int
```

--------------------------------

### Download Album by URL (Async)

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/README.md

Use this snippet to download an album directly using its URL. Ensure you have the necessary configuration file set up.

```python
import asyncio
from streamrip.config import Config
from streamrip.rip.main import Main

async def download():
    config = Config("~/.config/streamrip/config.toml")
    
    async with Main(config) as main:
        # Add album by URL
        await main.add("https://www.qobuz.com/us-en/album/rumours-fleetwood-mac/0603497941032")
        
        # Fetch metadata and download
        await main.resolve()
        await main.rip()

asyncio.run(download())
```

--------------------------------

### Download Last.fm Playlist with Fallback Source

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/cli-commands.md

Downloads tracks from a Last.fm playlist, using Qobuz as the primary source and Tidal as a fallback.

```bash
rip lastfm https://www.last.fm/user/username/playlists/123 \
  -s qobuz -fs tidal
```

--------------------------------

### Client.login()

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/clients.md

Authenticates with the streaming service using configured credentials. Raises AuthenticationError or MissingCredentialsError if authentication fails or credentials are not provided.

```APIDOC
## async login()

### Description
Authenticate with the streaming service using configured credentials.

### Method
ASYNC POST

### Endpoint
/login

### Raises
- `AuthenticationError`: If credentials are invalid
- `MissingCredentialsError`: If credentials are not configured
```

--------------------------------

### Fast Asynchronous Download with Progress Callback

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/downloadable.md

Downloads a URL to a file with a progress callback, optimized for high-speed downloads. It yields to the event loop only every 1MB. Ensure necessary headers are provided.

```python
async def download_with_progress(url, output_path):
    async def progress(chunk_size):
        print(f"Downloaded {chunk_size} bytes")
    
    headers = {"User-Agent": "Mozilla/5.0..."}
    await fast_async_download(output_path, url, headers, progress)
```

--------------------------------

### Downloads.add()

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/database.md

Inserts a row into the downloads table. Duplicate entries are silently ignored.

```APIDOC
## add(items: tuple)

### Description
Insert a row into the table.

### Parameters
#### Parameters
- **items** (tuple) - Values for all columns

### Note
Silently ignores duplicate entries (IntegrityError).
```

--------------------------------

### Edit Configuration File

Source: https://github.com/nathom/streamrip/wiki/Command-Line-Reference

Opens the Streamrip configuration file in the default editor or a specified editor like Vim.

```bash
rip config open
```

```bash
rip config open -v
```

--------------------------------

### Downloads Configuration

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/config.md

Configure settings for download behavior, including destination folder, subdirectory creation, concurrency, and rate limiting.

```python
from dataclasses import dataclass

@dataclass
class DownloadsConfig:
    folder: str
    source_subdirectories: bool
    disc_subdirectories: bool
    concurrency: bool
    max_connections: int
    requests_per_minute: int
    verify_ssl: bool
```

--------------------------------

### Converter Constructor

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/converter.md

Initializes a Converter instance with file path and optional conversion parameters.

```python
def __init__(
    self,
    filename: str,
    ffmpeg_arg: str | None = None,
    sampling_rate: int | None = None,
    bit_depth: int | None = None,
    copy_art: bool = True,
    remove_source: bool = False,
    show_progress: bool = False,
)
```

--------------------------------

### Default Configuration Paths and Version

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/config.md

Defines default paths for configuration files, download folders, and databases, as well as the current configuration version. These constants are used to set up Streamrip's default environment.

```python
import os
from pathlib import Path

# Assuming APP_DIR is defined elsewhere, e.g., APP_DIR = click.get_app_dir("streamrip")
# For demonstration, let's assume a placeholder
APP_DIR = Path.home() / ".streamrip"

DEFAULT_CONFIG_PATH = os.path.join(click.get_app_dir("streamrip"), "config.toml")
DEFAULT_DOWNLOADS_FOLDER = os.path.join(Path.home(), "StreamripDownloads")
DEFAULT_DOWNLOADS_DB_PATH = os.path.join(APP_DIR, "downloads.db")
DEFAULT_FAILED_DOWNLOADS_DB_PATH = os.path.join(APP_DIR, "failed_downloads.db")
CURRENT_CONFIG_VERSION = "2.2.0"
```

--------------------------------

### File Organization Configuration

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/configuration.md

Define templates for organizing downloaded music files and folders. This allows for customization of album folder names and track filenames.

```toml
[filepaths]
add_singles_to_folder = false
folder_format = "{albumartist}/{title} ({year})"
track_format = "{tracknumber:02d} {title}"
restrict_characters = true
truncate_to = 120

```

--------------------------------

### Download Behavior Configuration

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/configuration.md

Customize how downloads are managed, including the download folder, subdirectory creation, and network connection settings. Increase max_connections for faster downloads if you have good bandwidth.

```toml
[downloads]
folder = "~/StreamripDownloads"
source_subdirectories = true
disc_subdirectories = true
concurrency = true
max_connections = 6
requests_per_minute = 60
verify_ssl = true

```

--------------------------------

### Last.fm Configuration

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/config.md

Configure settings for Last.fm playlist integration, specifying primary and fallback sources for track searching.

```python
from dataclasses import dataclass

@dataclass
class LastFmConfig:
    source: str
    fallback_source: str
```

--------------------------------

### Client.get_session()

Source: https://github.com/nathom/streamrip/blob/dev/_autodocs/api-reference/clients.md

Creates and configures an aiohttp ClientSession with specified headers and SSL verification settings. Useful for establishing consistent HTTP connections.

```APIDOC
## async get_session(headers: dict | None = None, verify_ssl: bool = True)

### Description
Create an aiohttp ClientSession with appropriate headers and SSL configuration.

### Method
ASYNC GET

### Parameters
#### Query Parameters
- **headers** (dict) - Optional - Custom headers to include
- **verify_ssl** (bool) - Optional - Verify SSL certificates (default: True)

### Returns
Configured ClientSession
```