113 lines
2.6 KiB
Markdown
113 lines
2.6 KiB
Markdown
# Xbox Captures Downloader (Unofficial)
|
|
|
|
A Typer-based Python CLI that downloads **your** Xbox screenshots and game clips.
|
|
|
|
> ⚠️ **Disclaimer**: This uses *undocumented* Xbox MediaHub endpoints. They can change or stop working at any time. Use only with your own account and at your own risk. Respect Microsoft/Xbox terms.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- Download **screenshots** and **game clips** with readable filenames
|
|
- Concurrent downloads with progress bar
|
|
- Writes a `metadata.jsonl` for all fetched items
|
|
- Accepts tokens via:
|
|
- Direct `--token "XBL3.0 x=UHS;TOKEN"`
|
|
- `--token -` to read from **STDIN**
|
|
- Resolve **XUID** from **Gamertag** automatically
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
- Python 3.9+
|
|
- Packages:
|
|
```bash
|
|
pip install typer[all] requests tenacity tqdm
|
|
```
|
|
|
|
---
|
|
|
|
## Getting an auth token
|
|
|
|
You need an **Xbox Live** Authorization header value that looks like:
|
|
|
|
```
|
|
XBL3.0 x=<uhs>;<xsts_token>
|
|
```
|
|
|
|
You have three practical options:
|
|
|
|
### 1) Grab from your browser session (quick one-off)
|
|
|
|
1. Sign in at xbox.com, open **DevTools → Network**.
|
|
2. Trigger a view that loads captures.
|
|
3. Find a request and copy the **Authorization** request header (`XBL3.0 x=...;...`).
|
|
- mediahub.xboxlive.com
|
|
- user.auth.xboxlive.com
|
|
- xsts.auth.xboxlive.com
|
|
|
|
---
|
|
|
|
## Usage
|
|
|
|
### Basic
|
|
|
|
```bash
|
|
# With a Gamertag (script resolves XUID for you)
|
|
python xbox_captures_downloader.py pull \
|
|
--gamertag "YourGamertag" \
|
|
--token "XBL3.0 x=UHS;XSTS_TOKEN"
|
|
|
|
# With a known XUID
|
|
python xbox_captures_downloader.py pull \
|
|
--xuid 2533274791234567 \
|
|
--token "XBL3.0 x=UHS;XSTS_TOKEN"
|
|
```
|
|
|
|
### Keep tokens out of shell history
|
|
|
|
Create a `.env` file in the same directory:
|
|
```sh
|
|
XBOX_TOKEN="XBL3.0 x=UHS;XSTS_TOKEN"
|
|
XBOX_GAMERTAG="YourGamertag"
|
|
# or XBOX_XUID="2533274791234567"
|
|
```
|
|
|
|
```bash
|
|
# Read from STDIN (paste once, stays out of history)
|
|
echo "XBL3.0 x=UHS;XSTS_TOKEN" | \
|
|
python xbox_captures_downloader.py pull --token - --gamertag "YourGamertag"
|
|
|
|
# Read from clipboard
|
|
pbpaste | \
|
|
python xbox_captures_downloader.py pull --token - --gamertag "YourGamertag"
|
|
```
|
|
|
|
### Options
|
|
|
|
- `--media {screenshots|clips|both}` (default `both`)
|
|
- `--outdir PATH` (default `xbox_captures/`)
|
|
- `--concurrency N` (default `6`)
|
|
- `--max-per-page N` (default `100`)
|
|
- `--overwrite` (default `False`)
|
|
- `--save-metadata/--no-save-metadata` (default `True`)
|
|
|
|
---
|
|
|
|
## Output layout & filenames
|
|
|
|
- Files are stored under `xbox_captures/` in subfolders by kind.
|
|
- Names attempt to include `date` + `title` + a short ID, e.g.:
|
|
```
|
|
2024-07-18_211530__Forza_Horizon_5__abcdef1234.mp4
|
|
```
|
|
- A `metadata.jsonl` is appended with one JSON object per item.
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
Personal use only. No warranty. Use at your own risk.
|
|
|