Ptz Docs

PTZ Docs

Context: $ARGUMENTS

Anti-hallucination guardrail for PTZ protocol work. Fetches and searches the canonical Sony VISCA PDFs and the onvif.org profile pages. Pair with ptz-visca (wire protocol) and ptz-onvif (SOAP control) for actual camera operations.

Quick start

• Find a VISCA command byte sequence: → Step 2 (search --query "<command>")
• Read an ONVIF profile feature list: → Step 3 (section --page onvif-profile-t --id <heading>)
• Grab a full reference page: → Step 4 (fetch --page <name>)
• Pre-cache everything for offline: → Step 5 (index)
• See the full catalog: → Step 1 (list-pages)

When to use

• Verify a VISCA command byte code (e.g. 8x 01 06 01 VV WW YY YY ZZ ZZ FF for Pan-Tilt Drive) before sending.
• Confirm ONVIF service endpoint names (PTZ, Media, Imaging, Events, Recording, Analytics).
• Check which ONVIF profile applies (S deprecated, T replaces S, G recording, M analytics, A/C/D access).
• Cite the canonical Sony or ONVIF URL in a response.

Step 1 — Know the page catalog

uv run ${CLAUDE_SKILL_DIR}/scripts/ptzdocs.py list-pages

Only the HTML pages are text-searchable. PDF pages return a URL + note (PDF bytes aren't parsed).

Step 2 — Search first

uv run ${CLAUDE_SKILL_DIR}/scripts/ptzdocs.py search --query "Pan Tilt" --limit 5

Scope to a single page when you know which one:

uv run ${CLAUDE_SKILL_DIR}/scripts/ptzdocs.py search --query "GetProfiles" --page onvif-profile-s

Output per hit:

--- <page>:<line> — <nearest heading>
<URL with #anchor>
<snippet ±3 lines>

Use --format json for structured output.

Step 3 — Read one section

uv run ${CLAUDE_SKILL_DIR}/scripts/ptzdocs.py section --page onvif-profiles --id profile-s

--id accepts an anchor id (from [§...] in search hits) or a heading keyword.

Step 4 — Fetch whole page

uv run ${CLAUDE_SKILL_DIR}/scripts/ptzdocs.py fetch --page onvif-profile-s

Step 5 — Pre-cache

uv run ${CLAUDE_SKILL_DIR}/scripts/ptzdocs.py index

Override cache via PTZ_DOCS_CACHE=/path. Clear: clear-cache.

Gotchas

• VISCA PDFs are binary — not searchable by this skill. The script resolves the URL and confirms reachability but does NOT parse PDF bytes. For byte tables, download and open the PDF in a real reader, or use the curated excerpts in references/visca-commands.md / ptz-visca skill.
• ONVIF Profile S is deprecated as of 2027-03-31. New deployments should target Profile T (H.264 + H.265 + metadata + bidirectional audio). Profile S continues to work but won't be promoted.
• ONVIF Profile Q is formally deprecated — don't use it for anything new.
• WS-Discovery does NOT cross subnets. It's a link-local multicast at 239.255.255.250:3702. For remote cameras, use unicast GetCapabilities to a known IP or run a discovery proxy on the camera subnet.
• ONVIF uses SOAP 1.2 with WS-Security UsernameToken digest — PasswordText is allowed by spec but many cameras reject it; always compute the digest.
• VISCA-over-IP is NOT the same as VISCA-over-serial with a TCP tunnel. IP wraps each serial VISCA message in an 8-byte payload header (payload type, payload length, seq#). UDP port 52381. Sony, PTZOptics, AVer use the same wrapper.
• PTZOptics community ref isn't authoritative but it's widely used because the Sony PDFs are paywalled/login-gated for non-partner docs. Treat as a secondary source; cross-check with the Sony BRC/SRG PDFs.
• Fetching onvif.org PDFs — direct PDF URLs return bytes the script can confirm but doesn't index; the HTML profile pages (onvif-profiles, onvif-profile-s) are where search actually works.

Examples

Example 1 — "What's the VISCA byte sequence for Pan-Tilt Drive?"

uv run ${CLAUDE_SKILL_DIR}/scripts/ptzdocs.py search --query "Pan.Tilt" --regex --limit 5

Then open the PDF URL printed in the hit for the exact byte table.

Example 2 — "Does Profile T include metadata streaming?"

uv run ${CLAUDE_SKILL_DIR}/scripts/ptzdocs.py search --query "metadata" --page onvif-profile-overview

Example 3 — "Which PTZ subcommand is preset recall?"

uv run ${CLAUDE_SKILL_DIR}/scripts/ptzdocs.py search --query "preset recall"

Example 4 — "Profile S specification URL for citation"

uv run ${CLAUDE_SKILL_DIR}/scripts/ptzdocs.py list-pages | grep profile-s

Reference docs

• references/visca-commands.md — curated VISCA command byte table (the big excerpt that the PDF search cannot provide).
• references/onvif-services.md — per-profile ONVIF service matrix (Device/Media/PTZ/Imaging/Events/Recording/Analytics) and SOAP endpoint paths.

Troubleshooting

Error: unknown page: foo

Cause: Not in catalog. Solution: Run list-pages.

PDF page returns "binary page — URL only"

Cause: The skill doesn't parse PDFs (stdlib only). Solution: Open the printed URL in a browser/Preview/Acrobat, or search references/visca-commands.md which has the curated byte table.

Search returns zero hits on ONVIF pages

Cause: ONVIF marketing pages are light on technical detail. Solution: Drop the --page filter to search across all pages, or try onvif-profile-overview (the v2.1 PDF summary link).

Cache stale after upstream edits

Solution: clear-cache then index, or fetch --no-cache --page <name>.