yutto

https://github.com/yutto-dev/yutto
Admin
yutto is a cute and versatile command-line interface (CLI) tool for downloading videos from...
Tokens:34,516
Snippets:439
Trust Score:6.3
License:GPL-3.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Initialize OutputRequestOptions

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/configuration.md

Examples of initializing the configuration with various settings.

```python
# Default (current directory, auto format)
OutputRequestOptions()

# Custom directory
OutputRequestOptions(directory=Path("/videos"))

# MKV container, custom naming
OutputRequestOptions(
    format="mkv",
    directory=Path("/downloads/anime"),
    subpath_template="{title}_{avid}"
)

# Audio-only as MP3
OutputRequestOptions(
    audio_only_format="mp3",
    format="m4a"
)
```

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

### Configure resource selection examples

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/configuration.md

Examples for common resource download scenarios, including audio-only, metadata-only, and AI-translated subtitles.

```python
# Audio-only download
ResourceRequestOptions(
    video=False,
    audio=True,
    danmaku=False,
    subtitle=False
)

# Metadata-only
ResourceRequestOptions(
    video=False, audio=False, danmaku=False,
    subtitle=False, metadata=True, cover=False
)

# With AI subtitles
ResourceRequestOptions(ai_translation_language="en")
```

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

### Configure episode selection examples

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/configuration.md

Examples demonstrating various episode range filtering and date-based publication constraints.

```python
# Episodes 1-5
SelectionRequestOptions(episodes="1~5")

# Episodes 1, 3, 5
SelectionRequestOptions(episodes="1,3,5")

# All except last 2
SelectionRequestOptions(episodes="1~-3")

# Published between dates
SelectionRequestOptions(
    start_time="2024-01-01",
    end_time="2024-12-31"
)
```

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

### Integrate Yutto into CLI Application

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/core-application.md

Example setup for a CLI application using YuttoApplication, a DownloadManager workflow, and a CLI event renderer.

```python
from yutto.core.application import YuttoApplication
from yutto.core.execution import RequestExecutionScopeFactory
from yutto.core.request import DownloadRequest
from yutto.download_manager import DownloadManager
from yutto.cli.event_renderer import CliApplicationEventRenderer
from yutto.cli.request_adapter import download_request_from_namespace

# Parse CLI args
args = parser.parse_args(sys.argv[1:])

# Create event renderer for progress display
renderer = CliApplicationEventRenderer()

# Create application with execution strategy
scope_factory = RequestExecutionScopeFactory(
    credential_resolver=lambda request: get_auth_for_request(request)
)
app = YuttoApplication(
    scope_factory=scope_factory,
    workflow=DownloadManager(jobs=args.jobs),
    event_sink=renderer
)

# Convert CLI args to download request
request = download_request_from_namespace(args)

# Execute download
async with renderer:
    result = await app.download(request)
    print(f"Done: {len(result.items)} items")
```

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

### Example Usage of gen_audio_quality_priority

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/media-quality-codec.md

Shows how to generate a priority list starting from a specific quality level.

```python
from yutto.media.quality import gen_audio_quality_priority

# Try 320kbps first, then lower
priorities = gen_audio_quality_priority(30280)
# [30280, 30232, 30216, 30251, 30255, 30250]
```

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

### Configure ScopeRequestOptions instances

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/configuration.md

Examples of initializing scope options for single or batch video downloads.

```python
# Single video only
ScopeRequestOptions(batch=False)

# All episodes in series
ScopeRequestOptions(batch=True)

# Series + specials/OVA
ScopeRequestOptions(batch=True, with_extra_episodes=True)
```

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

### Configure AccessRequestOptions instances

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/configuration.md

Examples of initializing access options for specific authentication and membership requirements.

```python
# Use specific auth profile
AccessRequestOptions(auth_profile="premium")

# Require VIP membership
AccessRequestOptions(vip_strict=True)

# Fail if not authenticated
AccessRequestOptions(login_strict=True)
```

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

### Run common project tasks with just

Source: https://github.com/yutto-dev/yutto/blob/main/AGENTS.md

Use these commands to manage installation, testing, linting, and building the project.

```bash
just install
just run -- -h
just fmt
just lint
just test
just ci-install 3.11
just ci-test 3.11
just ci-e2e-test 3.11
just build
just docs-setup
just docs-build
```

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

### Configure NetworkRequestOptions Instances

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/configuration.md

Examples of initializing network options for custom proxy, concurrency limits, and rate limiting.

```python
# Custom proxy
NetworkRequestOptions(proxy="http://proxy.local:8080")

# Disable proxy
NetworkRequestOptions(proxy="no")

# Limit concurrency
NetworkRequestOptions(fetch_workers=2, download_workers=2)

# Ban specific CDN
NetworkRequestOptions(banned_mirrors_pattern="akamai")

# Smaller blocks, rate-limited
NetworkRequestOptions(
    block_size_bytes=256 * 1024,
    download_interval=500
)
```

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

### Handle DownloadItemSkipped Event

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/events.md

Example usage for logging skipped items.

```python
if isinstance(event, DownloadItemSkipped):
    print(f"⊘ {event.item}: {event.reason}")
```

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

### Handle DownloadProgress Event

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/events.md

Example logic for calculating and displaying progress percentages and transfer speeds.

```python
if isinstance(event, DownloadProgress):
    pct = 100 * event.current / event.total
    mb_per_sec = event.speed_per_second / 1e6
    print(f"{pct:.1f}% @ {mb_per_sec:.1f} MB/s")
```

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

### CLI Download with Authentication

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/auth.md

Examples of using different authentication methods when downloading content via CLI.

```bash
# Use default profile
yutto https://www.bilibili.com/video/BV1f34y1k7D5

# Use specific profile
yutto https://www.bilibili.com/video/BV1f34y1k7D5 --auth-profile vip

# Use inline credentials (priority over file)
yutto https://www.bilibili.com/video/BV1f34y1k7D5 --auth "SESSDATA=..."

# Anonymous (no credentials)
yutto https://www.bilibili.com/video/BV1f34y1k7D5
```

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

### Initialize DownloadRequest

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/configuration.md

A complete example demonstrating how to configure a DownloadRequest with source, access, scope, selection, resource, stream, output, network, and danmaku options.

```python
from pathlib import Path
from yutto.core.request import DownloadRequest

request = DownloadRequest(
    source=SourceRequestOptions(url="https://www.bilibili.com/video/BV1f34y1k7D5"),
    access=AccessRequestOptions(auth_profile="default", vip_strict=False),
    scope=ScopeRequestOptions(batch=True, with_extra_episodes=False),
    selection=SelectionRequestOptions(episodes="1~5", skip_preview=True),
    resources=ResourceRequestOptions(
        video=True,
        audio=True,
        danmaku=True,
        subtitle=True,
        metadata=True,
        cover=True,
        chapter_info=True,
        ai_translation_language="en"
    ),
    stream=StreamRequestOptions(
        video_quality=80,
        audio_quality=30280,
        video_download_codec="hevc",
        video_download_codec_priority=["hevc", "avc", "av1"]
    ),
    output=OutputRequestOptions(
        directory=Path("/videos/anime"),
        format="mkv",
        subpath_template="{title}"
    ),
    network=NetworkRequestOptions(
        fetch_workers=4,
        download_workers=4,
        proxy="no"
    ),
    danmaku=DanmakuRequestOptions(
        format="ass",
        font_size=28,
        opacity=0.8,
        block_colorful=True
    )
)
```

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

### Auth file TOML structure

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/auth.md

Example configuration format for the auth.toml file.

```toml
[profiles.default]
sessdata = "..."
bili_jct = "..."
updated_at = "2024-08-25T12:34:56Z"

[profiles.vip]
sessdata = "..."
bili_jct = "..."
```

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

### Handle DownloadArtifactCreated Event

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/events.md

Example usage for listing generated supplementary files.

```python
if isinstance(event, DownloadArtifactCreated):
    print(f"  Artifact: {event.path.name}")
```

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

### Configure DanmakuRequestOptions Instances

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/configuration.md

Examples of initializing danmaku options for custom rendering, filtering, and output formats.

```python
# ASS with custom rendering
DanmakuRequestOptions(
    format="ass",
    font="Microsoft YaHei",
    font_size=32,
    opacity=0.7,
    speed=1.5
)

# Minimal danmaku (block most types)
DanmakuRequestOptions(
    block_scroll=True,
    block_colorful=True,
    block_keyword_patterns=["spam", r"^[A-Z]{5,}$"]
)

# XML for external processing
DanmakuRequestOptions(format="xml")
```

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

### Authentication Setup

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/INDEX.md

Configures a request execution scope using a credential resolver to load authentication from a file.

```python
from yutto.auth import load_auth, default_auth_file

auth = load_auth(default_auth_file(), "default")
factory = RequestExecutionScopeFactory(credential_resolver=lambda r: auth)
```

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

### Handle DownloadStageChanged Event

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/events.md

Example logic for reacting to stage changes in the download lifecycle.

```python
if event.name == DownloadStage.DOWNLOADING:
    print(f"Downloading: {event.item}")
elif event.name == DownloadStage.POSTPROCESSING:
    print("Post-processing...")
```

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

### Handle NotFoundError

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/errors.md

Example of catching general resource not found errors.

```python
try:
    info = await get_ugc_video_info(scope, avid)
except NotFoundError as e:
    print(f"Video not found: {e.message}")
```

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

### Usage Example for RequestExecutionScopeFactory

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/execution-scope.md

Demonstrates how to instantiate the factory with a credential resolver and use it to open an execution scope.

```python
from yutto.core.execution import RequestExecutionScopeFactory
from yutto.core.request import DownloadRequest, SourceRequestOptions
from yutto.auth import AuthInfo

def resolve_auth(request: DownloadRequest) -> AuthInfo | None:
    # Load from file, env var, etc.
    return AuthInfo(SESSDATA="...", bili_jct="...")

factory = RequestExecutionScopeFactory(credential_resolver=resolve_auth)

request = DownloadRequest(source=SourceRequestOptions(url="BV1f34y1k7D5"))

async with factory.open(request) as scope:
    # Use scope for API calls
    result = await get_video_info(scope, avid)
    print(f"User is logged in: {scope.user_info_cache is not None}")
```

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

### Generate Audio Codec Priority List

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/media-quality-codec.md

Example usage of gen_acodec_priority to create a fallback list starting with a specific codec.

```python
from yutto.media.codec import gen_acodec_priority

# Try FLAC first (lossless), fallback
priorities = gen_acodec_priority("flac")
# ["flac", "mp4a", "eac3"]
```

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

### Authentication Configuration File Structure

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/auth.md

Example of the TOML structure for defining multiple authentication profiles.

```toml
[profiles.default]
sessdata = "1234567890abcdef1234567890abcdef"
bili_jct = "abcdef1234567890abcdef"
updated_at = "2024-08-25T15:30:00Z"

[profiles.vip]
sessdata = "fedcba0987654321fedcba0987654321"
bili_jct = "fedcba0987654321fedcba"
updated_at = "2024-08-25T12:00:00Z"

[profiles.testing]
sessdata = "test1234567890abcdefghij"
bili_jct = null
updated_at = "2024-08-24T10:00:00Z"
```

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

### Handle DownloadMediaSelected event

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/events.md

Example of checking the event type and accessing video or audio stream properties.

```python
if isinstance(event, DownloadMediaSelected):
    if event.video:
        print(f"Video: {event.video.width}x{event.video.height} {event.video.codec}")
    if event.audio:
        print(f"Audio: {event.audio.quality} {event.audio.codec}")
```

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

### Handle UnSupportedTypeError

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/errors.md

Example usage for catching unsupported type exceptions.

```python
try:
    info = await process_url(scope, url)
except UnSupportedTypeError as e:
    print(f"Not supported: {e.message}")
```

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

### Handle WrongUrlError

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/errors.md

Example usage for catching invalid URL exceptions.

```python
try:
    extractor = find_extractor("not-a-url")
except WrongUrlError as e:
    print(f"Invalid URL: {e.message}")
```

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

### Initiate a resolve task

Source: https://github.com/yutto-dev/yutto/blob/main/docs/guide/server.md

Submit a resolve task to list entry information from a source URL without starting a download.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resolve.start",
  "params": {
    "request": {
      "source": { "url": "https://www.bilibili.com/video/BV..." },
      "scope": { "batch": true }
    }
  }
}
```

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

### Handle EpisodeNotFoundError

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/errors.md

Example of catching episode not found errors during retrieval.

```python
try:
    item = await get_episode(scope, season_id, episode_num=999)
except EpisodeNotFoundError as e:
    print(f"Episode not found: {e.message}")
```

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

### DownloadBatchStarted Event Definition

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/events.md

Represents the start of a batch download operation containing multiple requests.

```python
@dataclass(frozen=True, slots=True)
class DownloadBatchStarted:
    total: int
```

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

### Generate Fallback Priority List

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/media-quality-codec.md

Creates a list of quality preferences starting from the specified target quality.

```python
from yutto.media.quality import gen_video_quality_priority

# Try 1080P first, then 720P, then lower
priorities = gen_video_quality_priority(80)
# [80, 74, 64, 32, 16, 127, 126, 125, 120, 116, 112, 100]
```

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

### Handle YuttoBaseException

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/errors.md

Example of catching the base exception and accessing its code and message attributes.

```python
try:
    # ... download code
except YuttoBaseException as e:
    print(f"Error: {e.message}")
    sys.exit(e.code.value)
```

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

### StreamRequestOptions Usage Examples

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/configuration.md

Various configurations for stream requests, including quality selection, codec preferences, and re-encoding settings.

```python
# Best quality, any codec
StreamRequestOptions(video_quality=127)

# 720P, prefer AV1
StreamRequestOptions(
    video_quality=64,
    video_download_codec="av1"
)

# Specific fallback order
StreamRequestOptions(
    video_download_codec="hevc",
    video_download_codec_priority=["hevc", "avc", "av1"]
)

# Re-encode to H.265 on save
StreamRequestOptions(video_save_codec="libx265")
```

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

### Handle NoAccessPermissionError

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/errors.md

Example of catching access permission errors to differentiate between private and members-only content.

```python
try:
    info = await get_ugc_video_info(scope, avid)
except NoAccessPermissionError as e:
    # Video is private or members-only
    if "会员" in e.message:
        print("Requires VIP membership")
    else:
        print("Video is private")
```

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

### gen_audio_quality_priority

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/media-quality-codec.md

Generates a fallback priority list for audio qualities starting from a specified desired quality.

```APIDOC
## gen_audio_quality_priority(quality: AudioQuality) -> list[AudioQuality]

### Description
Generates a fallback priority list starting from a desired audio quality. This is useful for determining the order in which to attempt stream downloads.

### Parameters
- **quality** (AudioQuality) - Required - The desired audio quality ID (e.g., 30280).

### Returns
- **list[AudioQuality]** - A list of quality IDs ordered by priority.

### Example
```python
from yutto.media.quality import gen_audio_quality_priority
priorities = gen_audio_quality_priority(30280)
```
```

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

### Use fetch_guard for API requests

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/execution-scope.md

Example usage of the fetch_guard context manager to wrap an asynchronous fetch operation.

```python
async with scope.fetch_guard():
    result = await fetch_json(scope, url)
```

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

### Generate Codec Priority List

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/media-quality-codec.md

Generates a list of codecs ordered by priority, starting with the specified desired codec.

```python
from yutto.media.codec import gen_vcodec_priority

# Try AV1 first (smallest), fallback
priorities = gen_vcodec_priority("av1")
# ["av1", "avc", "hevc"]
```

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

### Get default auth file location

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/auth.md

Retrieves the standard path for the authentication file based on the operating system's XDG configuration standards.

```python
from yutto.auth import default_auth_file

auth_file = default_auth_file()
print(auth_file)  # /home/user/.config/yutto/auth.toml
```

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

### gen_video_quality_priority

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/media-quality-codec.md

Generates a list of video quality IDs ordered by priority, starting from the specified desired quality and falling back to lower qualities.

```APIDOC
## gen_video_quality_priority

### Description
Generates a fallback priority list of video quality levels starting from a desired quality ID.

### Signature
`def gen_video_quality_priority(quality: VideoQuality) -> list[VideoQuality]`

### Parameters
- **quality** (VideoQuality) - Required - The desired starting quality ID (e.g., 80 for 1080P).

### Returns
- **list[VideoQuality]** - A list of quality IDs ordered by priority.

### Example
```python
from yutto.media.quality import gen_video_quality_priority

# Try 1080P first, then 720P, then lower
priorities = gen_video_quality_priority(80)
```
```

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

### Handle ResolveFailedError

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/errors.md

Example of catching ResolveFailedError when batch resolution fails.

```python
try:
    result = await download_manager.execute(scope_factory, [request1, request2])
except ResolveFailedError as e:
    # Multiple items failed to resolve
    print(f"All items failed: {e.message}")
```

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

### Handle WrongArgumentError

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/errors.md

Example usage for catching invalid argument exceptions.

```python
try:
    validate_episodes_arg("invalid~syntax")
except WrongArgumentError as e:
    print(f"Invalid argument: {e.message}")
```

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

### Perform a complete download with Yutto

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/README.md

Demonstrates initializing the application with authentication, configuring a download request, and executing the download process.

```python
import asyncio
from pathlib import Path
from yutto.core.application import YuttoApplication
from yutto.core.execution import RequestExecutionScopeFactory
from yutto.core.request import (
    DownloadRequest,
    SourceRequestOptions,
    StreamRequestOptions,
    OutputRequestOptions,
)
from yutto.download_manager import DownloadManager
from yutto.auth import AuthInfo, format_auth_inline

async def main():
    # Create credentials
    auth = AuthInfo(SESSDATA="your_sessdata", bili_jct="your_bili_jct")
    
    # Create scope factory with auth resolver
    def resolve_auth(request):
        return auth
    
    factory = RequestExecutionScopeFactory(credential_resolver=resolve_auth)
    
    # Create application
    app = YuttoApplication(
        scope_factory=factory,
        workflow=DownloadManager(jobs=2),
    )
    
    # Create download request
    request = DownloadRequest(
        source=SourceRequestOptions(url="BV1f34y1k7D5"),
        stream=StreamRequestOptions(
            video_quality=80,  # 1080P
            audio_quality=30280,  # 320kbps
        ),
        output=OutputRequestOptions(
            directory=Path("/videos"),
            format="mkv",
        ),
    )
    
    # Download
    result = await app.download(request)
    
    # Report results
    for item in result.items:
        print(f"{item.state}: {item.output_path}")

if __name__ == "__main__":
    asyncio.run(main())
```

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

### Handle HttpStatusError

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/errors.md

Example of catching an HTTP status error during a network request.

```python
try:
    result = await fetch_video_info(scope, video_id)
except HttpStatusError as e:
    print(f"Failed to fetch from API: {e.message}")
```

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

### Configure YuttoApplication with LoggingSink

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/events.md

Demonstrates how to implement a custom sink and register it with the YuttoApplication instance.

```python
class LoggingSink:
    async def on_event(self, event):
        print(f"Event: {type(event).__name__}: {event}")

app = YuttoApplication(
    scope_factory=scope_factory,
    workflow=DownloadManager(),
    event_sink=LoggingSink()
)
```

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

### Execute a complete download series

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/core-application.md

Demonstrates initializing the YuttoApplication with a DownloadManager and executing a batch download request for a specific series.

```python
import asyncio
from pathlib import Path
from yutto.core.application import YuttoApplication
from yutto.core.execution import RequestExecutionScopeFactory
from yutto.core.request import (
    DownloadRequest,
    SourceRequestOptions,
    ScopeRequestOptions,
    SelectionRequestOptions,
    ResourceRequestOptions,
    StreamRequestOptions,
    OutputRequestOptions,
)
from yutto.download_manager import DownloadManager
from yutto.core.events import (
    DownloadProgress,
    DownloadStageChanged,
    DownloadMediaSelected,
)

async def simple_event_handler(event):
    """Minimal event handler for download progress."""
    if isinstance(event, DownloadProgress):
        pct = 100 * event.current / event.total
        print(f"  {pct:.1f}% ({event.current}/{event.total})")
    elif isinstance(event, DownloadStageChanged):
        print(f"Stage: {event.name}")

class SimpleEventSink:
    async def on_event(self, event):
        await simple_event_handler(event)

async def download_anime_series():
    # Create scope factory (handles auth, sessions)
    scope_factory = RequestExecutionScopeFactory()
    
    # Create application
    app = YuttoApplication(
        scope_factory=scope_factory,
        workflow=DownloadManager(jobs=2),
        event_sink=SimpleEventSink()
    )
    
    # Build request: download series, episodes 1-12
    request = DownloadRequest(
        source=SourceRequestOptions(url="https://www.bilibili.com/bangumi/play/ss26711"),
        scope=ScopeRequestOptions(batch=True),
        selection=SelectionRequestOptions(episodes="1~12"),
        resources=ResourceRequestOptions(
            video=True,
            audio=True,
            danmaku=True,
            subtitle=True,
            metadata=False,
        ),
        stream=StreamRequestOptions(
            video_quality=80,  # 1080P
            audio_quality=30280,  # 320kbps
        ),
        output=OutputRequestOptions(
            directory=Path("/downloads/anime"),
            format="mkv",
        ),
    )
    
    # Execute
    result = await app.download(request)
    
    # Report results
    print(f"\nDownload complete!")
    print(f"  Total items: {len(result.items)}")
    done_count = sum(1 for item in result.items if item.state == "done")
    print(f"  Successfully downloaded: {done_count}")
    
    return result

# Run
if __name__ == "__main__":
    result = asyncio.run(download_anime_series())
```

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

### Initialize YuttoApplication

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/core-application.md

Defines the main orchestration class for managing download sessions.

```python
class YuttoApplication:
    """Frontend-independent orchestration for one yutto invocation."""
    
    def __init__(
        self,
        scope_factory: ExecutionScopeFactory,
        *,
        workflow: DownloadWorkflow,
        event_sink: DownloadEventSink | None = None,
        resolve_workflow: ResolveWorkflow | None = None,
    )
```

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

### gen_acodec_priority

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/media-quality-codec.md

Generates a fallback priority list for audio codecs, starting with the user-specified codec.

```APIDOC
## gen_acodec_priority

### Description
Generates a fallback priority list starting from the desired audio codec.

### Signature
`def gen_acodec_priority(audio_codec: AudioCodec) -> list[AudioCodec]`

### Parameters
- **audio_codec** (AudioCodec) - Required - Desired codec (mp4a, flac, or eac3).

### Returns
- **list[AudioCodec]** - A priority list starting with the desired codec.

### Example
```python
from yutto.media.codec import gen_acodec_priority

# Try FLAC first (lossless), fallback
priorities = gen_acodec_priority("flac")
# ["flac", "mp4a", "eac3"]
```
```

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

### Basic Download Implementation

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/INDEX.md

Initializes the Yutto application and executes a download request for a specific source URL.

```python
from yutto.core.application import YuttoApplication
from yutto.core.request import DownloadRequest, SourceRequestOptions

app = YuttoApplication(...)
request = DownloadRequest(source=SourceRequestOptions(url="BV1f34y1k7D5"))
result = await app.download(request)
```

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

### Configure Download Requests

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/media-quality-codec.md

Demonstrates various configurations for DownloadRequest, including high-quality, balanced, low-bandwidth, and audio-only scenarios.

```python
from yutto.core.request import DownloadRequest, StreamRequestOptions
from yutto.media.quality import video_quality_priority_default, audio_quality_priority_default
from yutto.media.codec import video_codec_priority_default, audio_codec_priority_default

# Best quality (8K if available, fallback progressively)
best_quality_request = DownloadRequest(
    stream=StreamRequestOptions(
        video_quality=127,  # Try 8K first
        audio_quality=30251,  # Try Hi-Res first
        video_download_codec="av1",  # Smallest files
        audio_download_codec="flac",  # Lossless
    )
)

# Balanced quality/size (1080P + 320kbps)
balanced_request = DownloadRequest(
    stream=StreamRequestOptions(
        video_quality=80,  # 1080P
        audio_quality=30280,  # 320kbps
        video_download_codec="hevc",  # Good compression
        audio_download_codec="mp4a",  # Compatible
    )
)

# Low bandwidth (720P + 128kbps)
low_bandwidth_request = DownloadRequest(
    stream=StreamRequestOptions(
        video_quality=64,  # 720P
        audio_quality=30232,  # 128kbps
        video_download_codec="avc",  # Best compatibility
        audio_download_codec="mp4a",
    )
)

# Audio-only (music, podcast)
audio_only_request = DownloadRequest(
    resources=ResourceRequestOptions(
        video=False,
        audio=True,
    ),
    stream=StreamRequestOptions(
        audio_quality=30280,  # 320kbps for music
        audio_download_codec="flac",  # Lossless
    ),
    output=OutputRequestOptions(
        audio_only_format="m4a",
    ),
)
```

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

### Execute Complete Download Workflow

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/results.md

Demonstrates initializing the Yutto application, executing a download request, and processing the resulting items and artifacts.

```python
import asyncio
from pathlib import Path
from yutto.core.application import YuttoApplication
from yutto.core.execution import RequestExecutionScopeFactory
from yutto.core.request import DownloadRequest, SourceRequestOptions, ScopeRequestOptions
from yutto.core.result import ItemState, ArtifactKind
from yutto.download_manager import DownloadManager

async def analyze_download_result():
    scope_factory = RequestExecutionScopeFactory()
    app = YuttoApplication(
        scope_factory=scope_factory,
        workflow=DownloadManager(jobs=2),
    )
    
    request = DownloadRequest(
        source=SourceRequestOptions(url="BV1f34y1k7D5"),
        output=OutputRequestOptions(directory=Path("/videos")),
    )
    
    result = await app.download(request)
    
    # Analyze results
    done_items = [item for item in result.items if item.state == ItemState.DONE]
    skipped_items = [item for item in result.items if item.state == ItemState.SKIPPED]
    
    print(f"Summary:")
    print(f"  Total: {len(result.items)}")
    print(f"  Done: {len(done_items)}")
    print(f"  Skipped: {len(skipped_items)}")
    
    # Examine media downloads
    for item in done_items:
        if item.has_downloaded_media:
            print(f"\n✓ {item.output_path.name}")
            
            # List all artifacts
            media = [a for a in item.artifacts if a.kind == ArtifactKind.MEDIA]
            subs = [a for a in item.artifacts if a.kind == ArtifactKind.SUBTITLE]
            danmaku = [a for a in item.artifacts if a.kind == ArtifactKind.DANMAKU]
            
            if media:
                print(f"  Media: {media[0].path.stat().st_size / 1e6:.1f} MB")
            if subs:
                print(f"  Subtitles: {len(subs)} file(s)")
            if danmaku:
                print(f"  Danmaku: {len(danmaku)} file(s)")
    
    # Show skipped
    for item in skipped_items:
        print(f"\n⊘ Skipped: {item.output_path}")
        print(f"  Reason: {item.skip_reason}")
    
    return result

if __name__ == "__main__":
    result = asyncio.run(analyze_download_result())
```

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

### Create and format AuthInfo

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/auth.md

Initialize credentials and convert them into an inline string format for use.

```python
from yutto.auth import AuthInfo, format_auth_inline

# Create credentials
auth = AuthInfo(
    SESSDATA="your_sessdata_here",
    bili_jct="your_bili_jct_here"
)

# Format as inline string
auth_str = format_auth_inline(auth["SESSDATA"], auth["bili_jct"])
# "SESSDATA=your_sessdata_here; bili_jct=your_bili_jct_here"
```

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

### Configure DownloadRequest Codecs

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/media-quality-codec.md

Demonstrates how to specify preferred codecs and fallback priority lists when creating a download request.

```python
from yutto.core.request import DownloadRequest, StreamRequestOptions

# Prefer HEVC for smaller file size
request = DownloadRequest(
    stream=StreamRequestOptions(video_download_codec="hevc")
)

# Fallback order: HEVC → AVC → AV1
request = DownloadRequest(
    stream=StreamRequestOptions(
        video_download_codec="hevc",
        video_download_codec_priority=["hevc", "avc", "av1"]
    )
)
```

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

### gen_vcodec_priority

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/media-quality-codec.md

Generates a fallback priority list for video codecs starting from the specified desired codec.

```APIDOC
## gen_vcodec_priority

### Description
Generates a fallback priority list of video codecs starting from the desired codec.

### Signature
`def gen_vcodec_priority(video_codec: VideoCodec) -> list[VideoCodec]`

### Parameters
- **video_codec** (VideoCodec) - Required - The desired codec to start the priority list with. Must be one of: "avc", "hevc", "av1".

### Returns
- **list[VideoCodec]** - A list of codecs ordered by priority.

### Example
```python
from yutto.media.codec import gen_vcodec_priority

# Try AV1 first (smallest), fallback
priorities = gen_vcodec_priority("av1")
# ["av1", "avc", "hevc"]
```
```

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

### YuttoApplication.download_all

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/core-application.md

Executes downloads for multiple requests, emitting batch events and delegating to the configured workflow.

```APIDOC
## async def download_all(requests: Sequence[DownloadRequest]) -> DownloadResult

### Description
Execute downloads for multiple requests. Emits batch events and queues each request before delegating to the workflow.

### Parameters
- **requests** (Sequence[DownloadRequest]) - One or more download requests with full configuration

### Returns
- **DownloadResult** - Download outcomes for all items across all requests
```

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

### Configure Download Request Codec

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/media-quality-codec.md

Demonstrates how to specify a preferred audio codec when creating a DownloadRequest.

```python
from yutto.core.request import DownloadRequest, StreamRequestOptions

# Prefer lossless FLAC
request = DownloadRequest(
    stream=StreamRequestOptions(audio_download_codec="flac")
)
```

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

### Initialize Request Execution Scope

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/execution-scope.md

Demonstrates setting up a RequestExecutionScopeFactory with credential resolution and lifecycle hooks.

```python
import asyncio
from yutto.core.execution import RequestExecutionScopeFactory
from yutto.core.request import DownloadRequest, SourceRequestOptions, NetworkRequestOptions
from yutto.auth import AuthInfo, load_auth, default_auth_file

async def main():
    # Credential resolver with file-based auth
    def resolve_credentials(request: DownloadRequest) -> AuthInfo | None:
        auth_file = default_auth_file()
        profile = request.access.auth_profile
        return load_auth(auth_file, profile)
    
    # Event handler for login announcements
    async def on_scope_open(scope, request):
        sessdata = scope.session.cookie("SESSDATA")
        if sessdata:
            print(f"✓ Authenticated as {request.access.auth_profile}")
    
    # Create factory
    factory = RequestExecutionScopeFactory(
        credential_resolver=resolve_credentials,
        on_open=on_scope_open,
    )
    
    # Create request with network options
    request = DownloadRequest(
        source=SourceRequestOptions(url="BV1f34y1k7D5"),
        network=NetworkRequestOptions(
            fetch_workers=4,
            download_workers=4,
            proxy="auto",
        ),
    )
    
    # Use scope
    async with factory.open(request) as scope:
        print(f"Fetch limiter slots: {scope.fetch_limiter._value}")
        print(f"Download workers: {scope.download_workers}")
        
        # All API calls use this scope
        # scope.user_info_cache is populated on first user API call
        # scope.wbi_img_cache is populated on first search/API call
        
        # Simulate API work
        async with scope.fetch_guard():
            await asyncio.sleep(0.1)  # simulate fetch
        
        print(f"Touched URLs: {len(scope.touched_urls)}")

if __name__ == "__main__":
    asyncio.run(main())
```

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

### Execute batch downloads with download_all

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/core-application.md

Processes multiple download requests and delegates execution to the configured workflow.

```python
async def download_all(
    self,
    requests: Sequence[DownloadRequest]
) -> DownloadResult
```

```python
from yutto.core.application import YuttoApplication
from yutto.core.request import DownloadRequest, SourceRequestOptions
from yutto.core.execution import RequestExecutionScopeFactory
from yutto.download_manager import DownloadManager

scope_factory = RequestExecutionScopeFactory()
app = YuttoApplication(
    scope_factory=scope_factory,
    workflow=DownloadManager(jobs=4),
    event_sink=my_event_sink
)

requests = [
    DownloadRequest(source=SourceRequestOptions(url="BV1f34y1k7D5")),
    DownloadRequest(source=SourceRequestOptions(url="ep395211")),
]

result = await app.download_all(requests)
print(f"Downloaded {len(result.items)} items")
```

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

### Configure Authentication via auth.toml

Source: https://github.com/yutto-dev/yutto/blob/main/skills/bilibili-video-download/SKILL.md

Use this configuration format to manually set credentials in the auth.toml file instead of passing them through command-line arguments.

```toml
[profiles.default]
sessdata = "用户的SESSDATA"
bili_jct = "用户的bili_jct"
```

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

### Display Project File Structure

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/INDEX.md

Visual representation of the documentation directory layout.

```text
/workspace/home/output/
├── README.md                    (Overview and quick navigation)
├── INDEX.md                     (This file)
├── core-application.md          (Main orchestration)
├── execution-scope.md           (Request environment)
├── configuration.md             (Download options)
├── types.md                     (Type definitions)
├── results.md                   (Result types)
├── api-modules.md               (API wrappers)
├── auth.md                      (Authentication)
├── events.md                    (Progress events)
├── media-quality-codec.md       (Quality/codec reference)
└── errors.md                    (Exception types)
```

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

### Progress Monitoring

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/INDEX.md

Implements an event handler to track and print download progress percentages.

```python
from yutto.core.events import DownloadProgress

class EventHandler:
    async def on_event(self, event):
        if isinstance(event, DownloadProgress):
            pct = 100 * event.current / event.total
            print(f"{pct:.1f}%")

app = YuttoApplication(..., event_sink=EventHandler())
```

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

### resolve.start

Source: https://github.com/yutto-dev/yutto/blob/main/docs/guide/server.md

Submits a resolution task to list stable information for a given source URL. This method is only available if server.info indicates support for it.

```APIDOC
## resolve.start

### Description
Submits a resolution task to list stable information for a given source URL without triggering a download. This allows front-end applications to render selectors before initiating a download via download.start.

### Method
JSON-RPC 2.0

### Parameters
- **request** (object) - Required - The request object containing the source URL and scope.
  - **source** (object) - Required - The source configuration.
    - **url** (string) - Required - The URL of the video or list to resolve.
  - **scope** (object) - Optional - The scope of the resolution.
    - **batch** (boolean) - Optional - Whether to perform a batch resolution.

### Request Example
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resolve.start",
  "params": {
    "request": {
      "source": { "url": "https://www.bilibili.com/video/BV..." },
      "scope": { "batch": true }
    }
  }
}
```

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

### ExecutionScope.__init__

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/execution-scope.md

Initializes a new execution scope with a provided HTTP session and concurrency settings.

```APIDOC
## ExecutionScope(session, fetch_workers=8, download_workers=8)

### Description
Initializes a runtime container for a single request's HTTP client, concurrency limits, and API caches.

### Parameters
- **session** (YuttoSession) - Required - Initialized HTTP client session.
- **fetch_workers** (int) - Optional - Max concurrent fetch semaphore slots (default: 8).
- **download_workers** (int) - Optional - Max concurrent download streams (default: 8).

### Raises
- **ValueError** - If fetch_workers < 1 or download_workers < 1.
```

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

### ResourceRequestOptions

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/configuration.md

Configuration model for specifying which media resources (video, audio, subtitles, etc.) to include in a download.

```APIDOC
## ResourceRequestOptions

### Description
Defines which resources to download and include for a given request.

### Parameters
- **video** (bool) - Optional - Download video stream. Default: True.
- **audio** (bool) - Optional - Download audio stream. Default: True.
- **danmaku** (bool) - Optional - Download danmaku comments. Default: True.
- **subtitle** (bool) - Optional - Download subtitles. Default: True.
- **metadata** (bool) - Optional - Download NFO metadata file. Default: False.
- **cover** (bool) - Optional - Fetch cover art. Default: True.
- **chapter_info** (bool) - Optional - Download chapter/scene markers. Default: True.
- **save_cover** (bool) - Optional - Save cover as separate file. Default: False.
- **ai_translation_language** (str | None) - Optional - Language code for AI-translated subtitles (e.g., "en"). Default: None.
```

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

### Request Audio Quality

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/media-quality-codec.md

Demonstrates how to specify audio quality when creating a download request.

```python
from yutto.core.request import DownloadRequest, StreamRequestOptions

# Request Hi-Res audio
request = DownloadRequest(
    stream=StreamRequestOptions(audio_quality=30251)
)

# Request 320kbps as fallback
request = DownloadRequest(
    stream=StreamRequestOptions(audio_quality=30280)
)
```

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

### Define OutputRequestOptions model

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/configuration.md

The base model for configuring download output parameters.

```python
class OutputRequestOptions(_RequestModel):
    directory: Path = Field(default_factory=Path)
    temporary_directory: Path | None = None
    format: Literal["infer", "mp4", "mkv", "mov"] = "infer"
    audio_only_format: Literal["infer", "m4a", "aac", "mp3", "flac", "mp4", "mkv", "mov"] = "infer"
    overwrite: bool = False
    subpath_template: str = "{auto}"
    metadata_format_premiered: str = TIME_DATE_FMT
    enforce_directory_boundary: bool = Field(default=False, exclude=True)
```

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

### YuttoApplication.resolve_all

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/core-application.md

Resolves items without downloading, useful for dry runs or discovery mode.

```APIDOC
## async def resolve_all(requests: Sequence[DownloadRequest]) -> ResolveResult

### Description
Resolve items without downloading (dry run / discovery mode). Requires `resolve_workflow` to be configured.

### Parameters
- **requests** (Sequence[DownloadRequest]) - Requests to resolve for item listing

### Returns
- **ResolveResult** - Listed items and any resolution failures

### Raises
- **RuntimeError** - If application was built without a resolve workflow
```

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

### Configure SourceRequestOptions

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/configuration.md

Defines the source URL or ID for the download request.

```python
class SourceRequestOptions(_RequestModel):
    url: str
```

```python
# Full URL
SourceRequestOptions(url="https://www.bilibili.com/video/BV1f34y1k7D5")

# Direct ID (auto-detected format)
SourceRequestOptions(url="BV1f34y1k7D5")
SourceRequestOptions(url="ep395211")
```

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

### Define NotFoundError

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/errors.md

General exception for missing resources such as deleted videos or invalid URLs.

```python
class NotFoundError(YuttoBaseException):
    code = ErrorCode.NOT_FOUND_ERROR  # 17
```

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

### Display Selected Media Streams

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/media-quality-codec.md

Use this event handler to inspect and print details of selected video and audio streams during a download process.

```python
from yutto.core.events import DownloadMediaSelected, SelectedVideoStream, SelectedAudioStream

async def display_selected_streams(event):
    if isinstance(event, DownloadMediaSelected):
        if event.video:
            v = event.video
            print(f"Video: {v.width}x{v.height} {v.codec} (quality={v.quality})")
        
        if event.audio:
            a = event.audio
            print(f"Audio: {a.codec} (quality={a.quality})")
```

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

### Define Default and Encrypted Priority Lists

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/media-quality-codec.md

Configuration lists for standard and encrypted audio quality priorities.

```python
audio_quality_priority_default = [30251, 30255, 30250, 30280, 30232, 30216]
```

```python
audio_encrypted_quality_priorities = [100010, 100009, 100008]
```

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

### Programmatic Authentication Usage

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/auth.md

Demonstrates how to load authentication profiles and inject them into a RequestExecutionScopeFactory.

```python
import asyncio
from pathlib import Path
from yutto.auth import load_auth, default_auth_file, AuthInfo
from yutto.core.execution import RequestExecutionScopeFactory
from yutto.core.request import DownloadRequest

def get_credentials(profile: str = "default") -> AuthInfo | None:
    auth_file = default_auth_file()
    return load_auth(auth_file, profile)

async def download_with_auth():
    auth = get_credentials("vip")
    if auth is None:
        print("No VIP profile found")
        return
    
    def resolver(request: DownloadRequest) -> AuthInfo | None:
        return auth
    
    factory = RequestExecutionScopeFactory(credential_resolver=resolver)
    
    # Use factory for download...
```

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

### load_auth_file(auth_file)

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/auth.md

Loads and parses the entire authentication TOML file into an AuthFileModel.

```APIDOC
## load_auth_file(auth_file)

### Description
Parses the specified auth TOML file. Returns None if the file is missing, invalid, or does not match the expected schema.

### Parameters
- **auth_file** (Path) - Required - The path to the auth.toml file.

### Returns
- **AuthFileModel | None** - The parsed model or None.
```

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

### DownloadWorkflow.execute

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/core-application.md

Executes a download workflow using the provided execution scope and request configuration.

```APIDOC
## DownloadWorkflow.execute

### Description
Defines the interface for download execution strategies.

### Method
async def execute(self, scope_factory: ExecutionScopeFactory, requests: Sequence[DownloadRequest]) -> DownloadResult

### Parameters
- **scope_factory** (ExecutionScopeFactory) - Required - Factory for creating request-scoped execution environments
- **requests** (Sequence[DownloadRequest]) - Required - Full configuration for each request

### Returns
- **DownloadResult** - Aggregated download outcomes
```

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

### DownloadBatchStarted

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/events.md

Emitted when a download operation begins in batch mode.

```APIDOC
## DownloadBatchStarted

### Description
Emitted when download begins with multiple requests (batch mode). Used to initialize progress UI and display batch summary.

### Fields
- **total** (int) - Total number of requests in batch
```

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

### NetworkRequestOptions

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/configuration.md

Configuration model for network, proxy, and concurrency settings.

```APIDOC
## NetworkRequestOptions

### Description
Configuration model for managing network requests, proxy settings, and download concurrency.

### Parameters
- **proxy** (str) - Optional - Proxy URL ("auto" = use environment, "no" = no proxy, or full URL). Default: "auto"
- **fetch_workers** (int) - Optional - Concurrent HTTP requests for metadata/API. Default: 8
- **download_workers** (int) - Optional - Concurrent streams for video/audio download. Default: 8
- **block_size_bytes** (int) - Optional - Chunk size for each download request (512 KiB). Default: 524288
- **download_interval** (int) - Optional - Delay in milliseconds between requests (rate limiting). Default: 0
- **banned_mirrors_pattern** (str | None) - Optional - Regex pattern to filter out CDN mirrors. Default: None
```

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

### YuttoApplication.download

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/results.md

Executes a download request using the Yutto application instance and returns the result of the operation.

```APIDOC
## YuttoApplication.download(request: DownloadRequest)

### Description
Initiates a download process based on the provided DownloadRequest configuration. Returns a result object containing the status of processed items.

### Parameters
- **request** (DownloadRequest) - Required - The configuration object containing source URL and output directory options.

### Response
- **result** (DownloadResult) - An object containing a list of items, their states (DONE, SKIPPED), and any associated failures.
```

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

### Access ItemResult properties

Source: https://github.com/yutto-dev/yutto/blob/main/_autodocs/results.md

Demonstrates accessing item state, skip reasons, and artifact information after a download.

```python
result = await app.download(request)

for item in result.items:
    print(f"Path: {item.output_path}")
    print(f"State: {item.state")}
    
    if item.state == ItemState.SKIPPED:
        print(f"Skip reason: {item.skip_reason}")
    else:
        print(f"Media downloaded: {item.has_downloaded_media}")
        print(f"Artifacts:")
        for artifact in item.artifacts:
            print(f"  {artifact.kind}: {artifact.path}")
```
Tokens:
Raw