docs: Add Remote loading guide (URLs, cloud, Google Drive, video) (#444)

* docs: Add Remote loading guide and document URL/cloud/Drive/video loading

Consolidate the URL-loading documentation into a standalone Guides page
(docs/remote.md) covering http/https + cloud (s3/gs/az) + Google Drive
loading, streaming modes, caching/clear_remote_cache, authentication and
security, embedded pkg.slp streaming, remote video (pyav), and error
handling/troubleshooting. Replace the large examples.md section with a
concise pointer, add the page to the nav, and add short autoref'd mentions
across install, formats, and the Video model docs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore: Add reencode to codespell ignore-words-list

Align the pyproject.toml codespell config with the CI workflow (.github/workflows/codespell.yml), which already ignores `reencode`. `reencode` is the literal `sio reencode` CLI subcommand name documented in docs/examples.md, docs/formats/index.md, and docs/model/video.md, so codespell must not rewrite it to "re-encode". This makes local codespell match CI.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: talmo

docs/examples.md

@@ -628,277 +628,24 @@ sio.save_coco(
 
 ## Loading from URLs
 
-Load `.slp` files directly from HTTP/HTTPS and cloud-storage URLs. Reads are
-lazy and range-based: for the default streaming mode only the bytes actually
-needed (typically a small fraction of the file) are pulled over the network.
-
-### Quickstart
-
-[`load_slp`][sleap_io.load_slp] (and the universal
-[`load_file`][sleap_io.load_file]) accept a URL anywhere a local path is
-accepted:
-
-```python
-import sleap_io as sio
-
-# Just works for http/https out of the box
-labels = sio.load_slp("https://example.com/path/labels.slp")
-
-# load_file also accepts URLs (dispatches by extension)
-labels = sio.load_file("https://example.com/path/labels.slp")
-```
-
-`pkg.slp` files with embedded frames work too — the embedded `HDF5Video`
-backends reopen the remote file lazily when you read frames, reusing the same
-streaming configuration.
-
-!!! info "What is and isn't supported"
-    URL loading currently covers `.slp`/`.pkg.slp` (including through the
-    universal [`load_file`][sleap_io.load_file]) and remote *media video* over
-    `http`/`https` (see [Remote video](#remote-video) below). Other *labels*
-    formats (NWB, COCO, Label Studio, JABS, DLC, TrackMate, LEAP, GeoJSON,
-    Ultralytics) are not yet implemented over URLs and raise
-    `NotImplementedError`; download the file locally first. These are tracked
-    as follow-ups.
-
-### Remote video
-
-[`load_video`][sleap_io.load_video] (and [`load_file`][sleap_io.load_file] for
-video extensions) can read a media video directly from an `http`/`https` URL:
+[`load_slp`][sleap_io.load_slp] and [`load_file`][sleap_io.load_file] accept a
+URL anywhere a local path is accepted, with lazy range-based streaming by
+default:
 
 ```python
 import sleap_io as sio
 
-# Reads frames lazily over the network; needs the [pyav] extra
-video = sio.load_video("https://example.com/path/video.mp4")
-frame = video[0]  # frames are decoded on demand
-```
-
-Supported container extensions are the same as for local media videos
-(`mp4`, `avi`, `mov`, `mj2`, `mkv`). Only `http` and `https` URLs are accepted
-for video — cloud schemes (`s3://`, `gs://`, …) are not supported for video
-loading. The URL's query string and fragment are ignored when detecting the
-extension, so pre-signed/tokenized URLs like
-`https://host/video.mp4?token=...` route correctly.
-
-Remote video requires the `pyav` extra, which is selected automatically as the
-backend for URLs:
-
-```bash
-pip install "sleap-io[pyav]"   # remote video support (provides `av`)
-```
-
-If the `av` package is missing, `load_video(url)` raises an `ImportError` with
-the install hint above.
-
-!!! danger "Security: remote video hands untrusted data to FFmpeg"
-    Decoding a remote video streams bytes from the URL into FFmpeg (via pyav).
-    FFmpeg's demuxers and decoders are a large, historically
-    vulnerability-prone attack surface (the CVE history for media parsers is
-    extensive), so a malicious URL or stream can attempt to exploit the
-    decoder running in your process.
-
-    To limit risk, sleap-io only ever passes `http`/`https` URLs through to the
-    decoder (no other schemes, no shell/protocol indirection). You should:
-
-    - **Load remote video only from sources you trust.** Treat an arbitrary
-      third-party URL the same as running untrusted code.
-    - **Sandbox untrusted inputs.** If you must decode video from an untrusted
-      source, do it in an isolated environment (container/VM with no
-      credentials, restricted network, and a non-privileged user) and keep
-      FFmpeg/pyav up to date.
-
-### Google Drive
-
-Google Drive file share links are recognized and resolved to a direct download
-automatically, so you can pass a Drive URL straight to
-[`load_slp`][sleap_io.load_slp] or [`load_file`][sleap_io.load_file]:
-
-```python
-import sleap_io as sio
-
-# Any of these Drive share-link shapes work:
-labels = sio.load_slp("https://drive.google.com/file/d/<FILE_ID>/view")
-labels = sio.load_slp("https://drive.google.com/uc?id=<FILE_ID>&export=download")
-labels = sio.load_slp("https://drive.google.com/open?id=<FILE_ID>")
-
-# load_file resolves the Drive link, sniffs the content, and routes it:
-labels = sio.load_file("https://drive.google.com/file/d/<FILE_ID>/view")
-```
-
-The file must be shared as **"Anyone with the link"** (no sign-in required).
-Because Drive download links carry no file extension and reject the `HEAD`/range
-requests that lazy streaming relies on, a Drive file is **fully downloaded into
-memory** during resolution (the `stream_mode`/cache keyword arguments do not
-apply). The two-hop "can't scan for viruses" confirmation page that Drive serves
-for larger files is handled transparently.
-
-Some limitations:
-
-- **Folder links are not supported** — pass a single-file share link
-  (`…/file/d/<FILE_ID>/view`), not a `…/drive/folders/<ID>` URL. A folder URL
-  raises a `ValueError`.
-- **Drive videos are not supported** — `load_video(<drive url>)` raises a
-  `NotImplementedError`. Download the video file first, then load it locally.
-- **Quota / permission errors** — if Drive returns its "too many users have
-  viewed or downloaded this file recently" page, a `RemoteIOError` is raised;
-  retry later or re-check the file's sharing settings.
-
-For `load_file`, the format is detected from the downloaded bytes (which costs
-one extra fetch). Pass an explicit `format=` (e.g. `format="slp"`) to skip the
-detection download.
-
-### Supported schemes and install matrix
-
-| Scheme | Requires | Notes |
-|--------|----------|-------|
-| `http`, `https` | nothing extra | Works with a plain `pip install sleap-io` |
-| `s3` | `sleap-io[cloud]` | Amazon S3 (via `s3fs`) |
-| `gs`, `gcs` | `sleap-io[cloud]` | Google Cloud Storage (via `gcsfs`) |
-| `az`, `abfs` | `sleap-io[cloud]` | Azure Blob / ADLS (via `adlfs`) |
-
-```bash
-pip install sleap-io               # http/https only
-pip install "sleap-io[cloud]"      # + s3, gs/gcs, az/abfs
-pip install "sleap-io[all]"        # everything (cloud schemes included)
-```
-
-```python
-# Cloud scheme (requires sleap-io[cloud])
-labels = sio.load_slp("s3://my-bucket/path/labels.slp")
-```
-
-!!! warning "Missing cloud extra"
-    Using a cloud scheme without the `[cloud]` extra raises an `ImportError`
-    whose message names the missing package and the
-    `pip install 'sleap-io[cloud]'` install hint.
-
-### Streaming modes
-
-Control how bytes are fetched with the `stream_mode` keyword argument:
-
-| `stream_mode` | Backing strategy | Memory | Disk cache | Revalidation | Best for |
-|---------------|------------------|--------|------------|--------------|----------|
-| `"auto"` (default) | fsspec `blockcache` | Low (LRU of `max_blocks`) | None | n/a | One-off lazy reads, low memory |
-| `"blockcache"` | fsspec `blockcache` | Low | None | n/a | Same as `auto` (explicit) |
-| `"cache"` | fsspec `simplecache` | Whole file on disk | Persistent | None | Repeated opens of an immutable file |
-| `"filecache"` | fsspec `filecache` | Whole file on disk | Persistent | ETag / `Last-Modified` after `cache_expiry` | Repeated opens of a file that may change |
-| `"download"` | Full read into memory | Whole file in RAM | None | n/a | Small files, ephemeral environments |
-
-```python
-# Default: lazy range reads, low memory
+# http/https works with a base install
 labels = sio.load_slp("https://example.com/labels.slp")
 
-# Persistent on-disk cache with daily ETag revalidation
-labels = sio.load_slp(
-    "https://example.com/labels.slp",
-    stream_mode="filecache",
-    cache_storage="~/.cache/sleap-io",
-    cache_expiry=86400,  # revalidate after a day
-)
-
-# Ephemeral full download into memory (no disk cache)
-labels = sio.load_slp("https://example.com/labels.slp", stream_mode="download")
-```
-
-The `"auto"`/`"blockcache"` reads can be tuned with `block_size` (range block
-size, default 1 MiB) and `max_blocks` (in-memory LRU cap per open file,
-default 32 → ~32 MiB per file).
-
-### Authentication
-
-Pass HTTP headers (such as a bearer token) with `headers=`:
-
-```python
-labels = sio.load_slp(
-    "https://my-org.example/private/labels.slp",
-    headers={"Authorization": "Bearer <token>"},
-)
+# Cloud schemes need the [cloud] extra (s3fs / gcsfs / adlfs)
+labels = sio.load_slp("s3://my-bucket/labels.slp")
 ```
 
-!!! warning "Headers are stripped on cross-origin redirect"
-    For security, sensitive headers (`Authorization`, `Cookie`,
-    `Proxy-Authorization`) are **dropped automatically** if the request is
-    redirected to a different origin (scheme/host/port). This prevents leaking
-    credentials to a third-party host and is intentional — if a download
-    redirects cross-origin (e.g. to a pre-signed CDN URL), put the credentials
-    in the redirect target's query string rather than in `headers`.
-
-    Cloud schemes (`s3://`, `gs://`, …) use their own per-provider credential
-    chains (environment variables, credential files, instance metadata) rather
-    than `headers=`.
-
-### Caching: location, override, and clearing
-
-For `"cache"` and `"filecache"` modes, downloaded files live in the directory
-you pass as `cache_storage=`. sleap-io writes a small marker file there so it
-can later identify and clean up only its own cache files.
-
-To clear the cache, call [`clear_remote_cache`][sleap_io.clear_remote_cache]
-with the **same** `cache_storage` you loaded with:
-
-```python
-import sleap_io as sio
-
-# Delete every sleap-io cache file in the directory
-sio.clear_remote_cache(cache_storage="~/.cache/sleap-io")
-
-# Or only files older than an hour (3600 seconds)
-sio.clear_remote_cache(cache_storage="~/.cache/sleap-io", older_than=3600)
-```
-
-!!! note "An explicit `cache_storage` is required to clear the cache"
-    `clear_remote_cache` only operates on a directory that contains the
-    sleap-io marker file, and it only deletes files matching fsspec's
-    cache-key naming pattern — so it will never touch unrelated files even if
-    you point it at a shared directory. It refuses to run on a directory with
-    no marker, or on forbidden paths like `/` or `$HOME`. Because fsspec's
-    *default* cache directory is a per-process temporary location that cannot
-    be cleared reliably, you must pass the explicit `cache_storage` you used
-    when loading.
-
-### CI and ephemeral environments
-
-In CI or other short-lived environments, prefer the default `stream_mode="auto"`
-(no persistent cache to manage), or scope a per-run cache to a temporary
-directory you control:
-
-```python
-import os
-import sleap_io as sio
-
-cache_dir = os.path.join(os.environ.get("RUNNER_TEMP", "/tmp"), "sleap-io-cache")
-labels = sio.load_slp(url, stream_mode="filecache", cache_storage=cache_dir)
-```
-
-### Troubleshooting
-
-- **`RemoteIOError`** — raised for HTTP-level failures (404 not found, 416 range
-  past end of file, 5xx after retries, connection errors, timeouts). The
-  exception carries a `status` (HTTP code or `None`) and a credential-redacted
-  `url` so tokens never leak into logs or tracebacks. See
-  [`RemoteIOError`][sleap_io.RemoteIOError].
-- **`ImportError` for cloud schemes** — install the cloud adapters with
-  `pip install 'sleap-io[cloud]'` (covers `s3`, `gs`/`gcs`, `az`/`abfs`).
-- **`RuntimeWarning` about `aiohttp`** — remote loading needs
-  `aiohttp >= 3.13.5` for safe cross-origin header stripping. If you see this
-  warning, upgrade with `pip install --upgrade 'aiohttp>=3.13.5'`.
-- **`ImportError` from `load_video(url)`** — remote video loading needs the
-  `pyav` extra; install it with `pip install 'sleap-io[pyav]'`. Only `http`/
-  `https` URLs are supported for video. See [Remote video](#remote-video) for
-  the security considerations of decoding untrusted remote video.
-- **Google Drive errors** — a `ValueError` means the link is a folder (pass a
-  `…/file/d/<ID>/view` file link) or the file ID could not be parsed; a
-  `RemoteIOError` mentioning a quota/permission page means the file is not shared
-  publicly or Drive is rate-limiting downloads. See [Google Drive](#google-drive).
-
-!!! note "See also"
-    - [`load_slp`][sleap_io.load_slp]: Full URL keyword-argument reference
-    - [`load_file`][sleap_io.load_file]: Universal loader with URL sniffing
-    - [`load_video`][sleap_io.load_video]: Loads remote media video over http/https
-    - [`clear_remote_cache`][sleap_io.clear_remote_cache]: Cache cleanup helper
-    - [`RemoteIOError`][sleap_io.RemoteIOError]: Remote I/O error surface
-    - [SLP Format](formats/slp.md): The on-disk `.slp` layout that URL loading streams
+This also covers `.pkg.slp` embedded-frame streaming, remote media video over
+`http`/`https`, and Google Drive share links. For streaming modes, caching,
+authentication, security notes, and troubleshooting, see the
+[Remote loading](remote.md) guide.
 
 ## Editing labels data
 

docs/formats/index.md

@@ -14,6 +14,11 @@ sleap-io provides a unified interface for reading and writing pose tracking data
 
 ::: sleap_io.io.main.save_video
 
+Media videos can also be read from `http`/`https` URLs with
+[`load_video`][sleap_io.load_video] (requires the `pyav` extra; cloud schemes
+and Google Drive are not supported for video). See
+[Remote video](../examples.md#loading-from-urls).
+
 ### Norpix .seq Format
 
 The `.seq` format is used by StreamPix / Norpix for high-speed video recording, commonly used in behavioral neuroscience. sleap-io provides native read support for `.seq` files via the [`SeqVideo`][sleap_io.SeqVideo] backend.
@@ -43,6 +48,8 @@ sio reencode recording.seq -o recording.mp4
 
 The native SLEAP format stores complete pose tracking projects including videos, skeletons, and annotations. SLP is the primary format with full round-trip support for bounding boxes (format 1.7+), regions of interest (ROIs), and segmentation masks (format 1.5+).
 
+`.slp` and `.pkg.slp` files can also be loaded directly from `http`/`https`, cloud (`s3://`, `gs://`, `az://`), and Google Drive URLs with lazy range-based streaming via [`load_slp`][sleap_io.load_slp] — see [Loading from URLs](../examples.md#loading-from-urls).
+
 !!! tip "Detailed Format Specification"
     For comprehensive documentation of the SLP file format including HDF5 layout, data structures, and version history, see the **[SLP File Format Reference](slp.md)**.
 
@@ -580,6 +587,8 @@ sleap-io automatically detects file formats based on:
 2. **File content**: For ambiguous extensions like `.h5` (JABS vs DLC) or `.json` (Label Studio vs COCO)
 3. **Explicit format**: Pass `format` parameter to override auto-detection
 
+For URLs, ambiguous extensions (`.h5`, `.json`, `.csv`) are disambiguated with a magic-byte sniff via a Range request, controllable with [`load_file`][sleap_io.load_file]'s `sniff=` argument. See [Loading from URLs](../examples.md#loading-from-urls).
+
 ## Format Conversion Examples
 
 ### Convert Between Formats
@@ -658,6 +667,9 @@ Different formats have varying capabilities:
 ******Ultralytics segmentation polygons stored as ROIs
 *******TrackMate auto-detects sibling `.tif`/`.tiff` video files
 
+!!! note "Remote URL loading"
+    Loading from a URL is currently supported only for SLEAP `.slp`/`.pkg.slp` (labels) and `http`/`https` media video; all other labels formats raise `NotImplementedError` over a URL — download the file locally first. See [Loading from URLs](../examples.md#loading-from-urls).
+
 ## See Also
 
 - [Data Model](../model/index.md): Understanding the core data structures

docs/formats/slp.md

@@ -760,6 +760,9 @@ The `/negative_frames` dataset is optional. Files without negative frames will n
 
 For large SLP files with hundreds of thousands of frames, sleap-io provides a lazy loading mode that defers [`Labels`][sleap_io.Labels] object creation until needed.
 
+!!! tip "Streaming from a URL"
+    `.slp`/`.pkg.slp` files can be opened straight from `http`/`https`, cloud, or Google Drive URLs via [`load_slp`][sleap_io.load_slp] with lazy range-based reads (embedded `pkg.slp` frames reopen the remote file on demand). See [Loading from URLs](../examples.md#loading-from-urls).
+
 ### Architecture
 
 ```

docs/index.md

@@ -23,7 +23,7 @@ does *not* include labeling, training, or inference.
 - **Codecs** -- Convert to/from NumPy arrays, DataFrames (pandas/polars), and dictionaries ([guide](codecs.md))
 - **Video I/O** -- Read any video format via pluggable backends (FFMPEG, OpenCV, PyAV) with a NumPy-like interface ([model](model/video.md))
 - **Lazy loading** -- Load large SLP files up to 90x faster by deferring object creation ([details](formats/slp.md#lazy-loading))
-- **Remote URLs** -- Load `.slp` files directly from `https://`, `s3://`, `gs://`, and `az://` URLs with lazy range-based reads and optional persistent caching ([guide](examples.md#loading-from-urls))
+- **Remote URLs** -- Load `.slp`/`.pkg.slp` and remote media video directly from `https://`, `s3://`, `gs://`, `az://`, and Google Drive URLs with lazy range-based reads and optional persistent caching ([guide](remote.md))
 - **Dataset splits** -- Create train/val/test splits and export to formats like Ultralytics YOLO ([example](examples.md#make-trainingvalidationtest-splits))
 
 ## Installation

docs/install.md

@@ -128,7 +128,9 @@ sio --version
     uv tool install sleap-io  # Basic installation
     ```
 
-    Video support via imageio-ffmpeg is always included.
+    Video support via imageio-ffmpeg is always included. The `[all]` extra also
+    includes the cloud-storage adapters (`s3fs`, `gcsfs`, `adlfs`) needed to
+    load `.slp` files from `s3://`/`gs://`/`az://` URLs.
 
 See the [CLI documentation](cli.md) for a complete command reference.
 
@@ -380,11 +382,16 @@ sleap-io uses optional dependencies for specific features:
 | Extra | Packages | Purpose |
 |-------|----------|---------|
 | `opencv` | `opencv-python` | Fastest video backend (2-3x faster) |
-| `pyav` | `av` | Balanced speed/features video backend |
+| `pyav` | `av` | Balanced speed/features video backend; required for loading remote media video over `http`/`https` |
+| `cloud` | `s3fs`, `gcsfs`, `adlfs` | Load `.slp` from cloud-storage URLs (`s3://`, `gs://`/`gcs://`, `az://`/`abfs://`) |
 | `mat` | `pymatreader` | LEAP `.mat` file support |
 | `polars` | `polars`, `pyarrow` | Fast dataframe operations |
 | `all` | All of the above | Everything included |
 
+`http`/`https` URLs work with the base install; cloud-storage URLs need the
+`cloud` extra and remote media video needs the `pyav` extra. See
+[Loading from URLs](examples.md#loading-from-urls).
+
 Install specific extras:
 
 ```bash