Den.Dev.FrameDrop.CLI 0.0.1

FrameDrop

A cross-platform library and tool written on top of .NET for downloading Xbox screenshots and video recordings.

Getting started

The CLI is the primary way to use FrameDrop — it handles authentication, listing, and bulk downloading of your Xbox captures in one tool.

Authentication note

FrameDrop uses the Entra ID client application ID for the Xbox App for Windows (000000004424da1f). The mediahub APIs that serve screenshots and game clips require permissions that are not granted to third-party registered applications, so we reuse the first-party Xbox App identity.

When you sign in, the browser will redirect to https://login.live.com/oauth20_desktop.srf?code=<CODE>&.... Because this is a desktop redirect URI, the page will likely show an error or go blank — that's expected. To grab the authorization code:

1. Open your browser's developer tools (F12) before signing in.
2. Switch to the Network tab.
3. After signing in, look for the request to oauth20_desktop.srf.
4. Copy the code query parameter from that URL and paste it back into FrameDrop.

Prerequisites

• .NET 10 SDK or later

Build

cd src/dotnet/Den.Dev.FrameDrop
dotnet build

Usage

Run from the build output directory:

cd src/dotnet/Den.Dev.FrameDrop/Den.Dev.FrameDrop.CLI/bin/Debug/net10.0
./framedrop <command>

Or with dotnet run:

cd src/dotnet/Den.Dev.FrameDrop
dotnet run --project Den.Dev.FrameDrop.CLI -- <command>

Commands

framedrop auth login

Starts the SISU authentication flow to connect your Xbox Live account.

1. FrameDrop attempts to restore a previous session from cached tokens.
2. If no valid session exists, it generates an authentication URL.
3. Open the URL in your browser and sign in with your Microsoft account.
4. After signing in, you'll be redirected to a URL containing a code parameter. Copy that code.
5. Paste the code back into the CLI to complete authentication.

framedrop auth login

Use --verbose to see HTTP request/response details during login:

framedrop auth login --verbose

framedrop auth status

Displays your current authentication state, including gamertag, XUID, and token expiration.

framedrop auth status

framedrop auth logout

Clears all stored authentication tokens.

framedrop auth logout

framedrop list

Lists all Xbox captures (screenshots and videos) in your cloud storage. Fetches all pages from both the screenshots and game clips APIs, then displays them in a table sorted by upload date (newest first).

framedrop list

The table shows:

Use --verbose to dump the raw JSON responses from the Xbox Live API (useful for debugging field names and response structure):

framedrop list --verbose

framedrop download

Downloads captures from Xbox cloud storage to your local machine.

framedrop download [options]

Options:

Behavior:

• Fetches all available captures across all pages (using continuation tokens for pagination).
• Pre-scans the output directory before downloading. Files that already exist on disk with the correct file size are skipped automatically — re-running the command is safe and only downloads new or incomplete captures.
• Shows a live progress display with per-file progress bars (title, progress, percentage, downloaded bytes, transfer speed) for active downloads. Completed files disappear from the display.
• An overall status line tracks total progress: count completed, bytes downloaded vs total, and any failures.
• Prints a final summary with downloaded count/size, already-on-disk count, and failure count.

Examples:

Download all captures:

framedrop download

Download only videos to a specific directory with 5 concurrent downloads:

framedrop download --type videos --output ~/xbox-clips --parallel 5

Download only screenshots:

framedrop download --type screenshots

Token Storage

Authentication tokens are encrypted at rest and stored locally:

• Windows: %LOCALAPPDATA%\Den.Dev\FrameDrop\tokens.bin
• Linux: ~/.local/share/Den.Dev/FrameDrop/tokens.bin

Tokens are encrypted using AES-256-GCM with a PBKDF2-SHA256 derived key (600,000 iterations). The key is bound to the current machine and user (MachineName + UserName). If the token file is corrupted or cannot be decrypted, it is automatically deleted and you will need to re-authenticate.