init

README.md

@@ -0,0 +1,113 @@
+# 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**
+  - `--token clip` to read from **clipboard** (with validation)
+- 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.
+