arkaos 4.30.0 → 4.32.0

package/departments/dev/skills/watch/references/claude-video.LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bradley Bonanno
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/departments/dev/skills/watch/scripts/config.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Shared /watch configuration helpers (ArkaOS-native).
+
+Every filesystem anchor resolves at CALL time, never import time, so a
+redirected HOME (tests, sandboxes) always takes effect. Key resolution
+order: environment -> ~/.arkaos/keys.json (managed by `/arka keys`) ->
+~/.arkaos/watch.env -> ./.env.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+DEFAULT_DETAIL = "balanced"
+
+DETAILS = {"transcript", "efficient", "balanced", "token-burner"}
+
+
+def arkaos_home() -> Path:
+    """User-data root — ~/.arkaos, or ARKAOS_HOME when set."""
+    override = os.environ.get("ARKAOS_HOME")
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".arkaos"
+
+
+def config_file() -> Path:
+    return arkaos_home() / "watch.env"
+
+
+def keys_file() -> Path:
+    return arkaos_home() / "keys.json"
+
+
+def telemetry_file() -> Path:
+    return arkaos_home() / "telemetry" / "watch-usage.jsonl"
+
+
+def read_env_file(path: Path | None = None) -> dict[str, str]:
+    if path is None:
+        path = config_file()
+    values: dict[str, str] = {}
+    if not path.exists():
+        return values
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return values
+    for line in lines:
+        raw = line.strip()
+        if not raw or raw.startswith("#") or "=" not in raw:
+            continue
+        key, _, value = raw.partition("=")
+        value = value.strip()
+        if len(value) >= 2 and value[0] in ('"', "'") and value[-1] == value[0]:
+            value = value[1:-1]
+        else:
+            # Strip an inline comment (a '#' preceded by whitespace) from an
+            # unquoted value. Without this, `WATCH_DETAIL=balanced  # note`
+            # parses as "balanced  # note", fails validation, and silently
+            # falls back to the default. Keeps '#' inside quotes / API keys.
+            for i, ch in enumerate(value):
+                if ch == "#" and i > 0 and value[i - 1] in " \t":
+                    value = value[:i].rstrip()
+                    break
+        values[key.strip()] = value
+    return values
+
+
+def read_keys_json() -> dict[str, str]:
+    """API keys stored by `/arka keys` (~/.arkaos/keys.json). Fail-open."""
+    path = keys_file()
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    return {str(k): str(v) for k, v in data.items() if v}
+
+
+def resolve_api_key(name: str) -> str | None:
+    """env -> ~/.arkaos/keys.json -> ~/.arkaos/watch.env -> ./.env."""
+    value = os.environ.get(name)
+    if value and value.strip():
+        return value.strip()
+    value = read_keys_json().get(name)
+    if value and value.strip():
+        return value.strip()
+    for path in (config_file(), Path.cwd() / ".env"):
+        value = read_env_file(path).get(name)
+        if value and value.strip():
+            return value.strip()
+    return None
+
+
+def get_config() -> dict[str, object]:
+    file_values = read_env_file()
+
+    detail = (
+        os.environ.get("WATCH_DETAIL")
+        or file_values.get("WATCH_DETAIL")
+        or DEFAULT_DETAIL
+    )
+    if detail not in DETAILS:
+        detail = DEFAULT_DETAIL
+
+    return {
+        "detail": detail,
+        "config_file": str(config_file()),
+    }
+
+
+def frame_cap(detail: str) -> int | None:
+    if detail == "efficient":
+        return 50
+    if detail == "balanced":
+        return 100
+    if detail == "token-burner":
+        return None
+    if detail == "transcript":
+        return None
+    return 100
+
+
+def record_telemetry(event: dict) -> None:
+    """Append one usage record to ~/.arkaos/telemetry/watch-usage.jsonl.
+
+    Observability must never break a watch run: filesystem failures
+    (OSError) are reported to stderr and swallowed (fail-open). Callers
+    pass only JSON-serializable scalars, so serialization cannot raise.
+    """
+    try:
+        path = telemetry_file()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        record = {"ts": round(time.time(), 3), **event}
+        with path.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(record, ensure_ascii=False) + "\n")
+    except OSError as exc:
+        print(f"[watch] telemetry write skipped: {exc}", file=sys.stderr)

package/departments/dev/skills/watch/scripts/download.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""Download a video via yt-dlp, or resolve a local file path.
+
+Also fetches subtitles (manual first, then auto-generated) in VTT format so
+transcribe.py can parse them without needing Whisper.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from urllib.parse import urlparse
+
+VIDEO_EXTS = {".mp4", ".mkv", ".webm", ".mov", ".m4v", ".avi", ".flv", ".wmv"}
+
+
+def is_url(source: str) -> bool:
+    if source.startswith("-"):
+        return False
+    parsed = urlparse(source)
+    return parsed.scheme in ("http", "https") and bool(parsed.netloc)
+
+
+def resolve_local(path: str) -> dict:
+    p = Path(path).expanduser().resolve()
+    if not p.exists():
+        raise SystemExit(f"File not found: {p}")
+    if p.suffix.lower() not in VIDEO_EXTS:
+        print(
+            f"[watch] warning: {p.suffix} is not a known video extension, proceeding anyway",
+            file=sys.stderr,
+        )
+    return {
+        "video_path": str(p),
+        "subtitle_path": None,
+        "info": {"title": p.name, "url": str(p)},
+        "downloaded": False,
+    }
+
+
+def _pick_subtitle(out_dir: Path) -> Path | None:
+    candidates = sorted(out_dir.glob("video*.vtt"))
+    if not candidates:
+        return None
+    preferred = [
+        c for c in candidates
+        if any(marker in c.name for marker in (".en.", ".en-US.", ".en-GB.", ".en-orig."))
+    ]
+    return preferred[0] if preferred else candidates[0]
+
+
+def _pick_video(out_dir: Path) -> Path | None:
+    for ext in (".mp4", ".mkv", ".webm", ".mov", ".m4a", ".mp3", ".opus"):
+        for candidate in out_dir.glob(f"video*{ext}"):
+            return candidate
+    for candidate in out_dir.glob("video.*"):
+        if candidate.suffix.lower() in VIDEO_EXTS:
+            return candidate
+    return None
+
+
+def fetch_captions(url: str, out_dir: Path) -> dict:
+    """Fetch metadata and best available VTT captions without downloading video."""
+    if shutil.which("yt-dlp") is None:
+        raise SystemExit("yt-dlp is not installed. Install with: brew install yt-dlp")
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    output_template = str(out_dir / "video.%(ext)s")
+    cmd = [
+        "yt-dlp",
+        "--skip-download",
+        "--write-info-json",
+        "--write-subs",
+        "--write-auto-subs",
+        "--sub-langs", "en.*",
+        "--sub-format", "vtt",
+        "--convert-subs", "vtt",
+        "--no-playlist",
+        "--ignore-errors",
+        "-o", output_template,
+        "--",
+        url,
+    ]
+    subprocess.run(cmd, stdout=sys.stderr, stderr=sys.stderr)
+    subtitle = _pick_subtitle(out_dir)
+    info = _read_info(out_dir / "video.info.json", url)
+    return {
+        "video_path": None,
+        "subtitle_path": str(subtitle) if subtitle else None,
+        "info": info or {"url": url},
+        "downloaded": False,
+    }
+
+
+def _read_info(info_path: Path, url: str) -> dict:
+    info: dict = {}
+    if info_path.exists():
+        try:
+            raw = json.loads(info_path.read_text(encoding="utf-8"))
+            info = {
+                "title": raw.get("title"),
+                "uploader": raw.get("uploader") or raw.get("channel"),
+                "duration": raw.get("duration"),
+                "url": raw.get("webpage_url") or url,
+            }
+        except Exception as exc:
+            print(f"[watch] info.json parse failed: {exc}", file=sys.stderr)
+            info = {"url": url}
+    return info
+
+
+def download_url(
+    url: str,
+    out_dir: Path,
+    audio_only: bool = False,
+) -> dict:
+    if shutil.which("yt-dlp") is None:
+        raise SystemExit("yt-dlp is not installed. Install with: brew install yt-dlp")
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    output_template = str(out_dir / "video.%(ext)s")
+
+    fmt = "ba/bestaudio" if audio_only else "bv*[height<=720]+ba/b[height<=720]/bv+ba/b"
+    cmd = [
+        "yt-dlp",
+        "-N", "8",
+        "-f", fmt,
+        "--merge-output-format", "mp4",
+        "--write-info-json",
+        "--write-subs",
+        "--write-auto-subs",
+        "--sub-langs", "en.*",
+        "--sub-format", "vtt",
+        "--convert-subs", "vtt",
+        "--no-playlist",
+        "--ignore-errors",
+        "-o", output_template,
+        "--",
+        url,
+    ]
+
+    # yt-dlp may exit non-zero if a subtitle variant fails (e.g. 429) even when
+    # the video itself downloaded fine. Treat "video file present" as success.
+    result = subprocess.run(cmd, stdout=sys.stderr, stderr=sys.stderr)
+    video = _pick_video(out_dir)
+    if video is None:
+        raise SystemExit(
+            f"yt-dlp did not produce a video file in {out_dir} (exit {result.returncode})"
+        )
+
+    subtitle = _pick_subtitle(out_dir)
+    info = _read_info(out_dir / "video.info.json", url)
+
+    return {
+        "video_path": str(video),
+        "subtitle_path": str(subtitle) if subtitle else None,
+        "info": info or {"url": url},
+        "downloaded": True,
+    }
+
+
+def download(
+    source: str,
+    out_dir: Path,
+    audio_only: bool = False,
+) -> dict:
+    if is_url(source):
+        return download_url(source, out_dir, audio_only=audio_only)
+    return resolve_local(source)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 3:
+        print("usage: download.py <url-or-path> <out-dir>", file=sys.stderr)
+        raise SystemExit(2)
+    result = download(sys.argv[1], Path(sys.argv[2]))
+    print(json.dumps(result, indent=2))