# 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.