@playcraft/cli 0.0.43 → 0.0.46

package/project-template/skills/_shared/scripts/gen-placeholder-audio.py

@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+"""Generate develop-stage audio placeholders: spectral (default), silent, or tone."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from placeholder_audio_lib import (
+    build_aevalsrc_expression,
+    build_spectral_strokes,
+    render_spectrogram_score_png,
+    spectrogram_score_path_for,
+    strokes_to_sidecar,
+)
+from placeholder_lib import role_short, sidecar_path_for, write_placeholder_sidecar
+
+SIDECAR_VERSION = 2
+DEFAULT_SFX_DURATION = 0.35
+DEFAULT_BGM_DURATION = 4.0
+VALID_MODES = {"spectral", "silent", "tone"}
+
+
+def require_ffmpeg() -> str:
+    ffmpeg = shutil.which("ffmpeg")
+    if not ffmpeg:
+        raise RuntimeError("ffmpeg is required for audio placeholders (install ffmpeg)")
+    return ffmpeg
+
+
+def normalize_output_path(path: str | Path) -> Path:
+    out = Path(path)
+    if not out.suffix:
+        return out.with_suffix(".mp3")
+    return out
+
+
+def default_duration(audio_type: str, duration: float | None) -> float:
+    if duration is not None:
+        return max(0.05, float(duration))
+    if audio_type == "bgm":
+        return DEFAULT_BGM_DURATION
+    return DEFAULT_SFX_DURATION
+
+
+def infer_role(label: str, audio_type: str) -> str:
+    name = (label or "").strip().lower()
+    if audio_type == "bgm" or name.startswith(("bgm_", "music_", "theme_")):
+        return "bgm · 背景音乐"
+    if name.startswith(("ui_", "click_", "btn_")):
+        return "ui sfx · 界面音效"
+    if name.startswith(("vfx_", "fx_")):
+        return "vfx sfx · 特效音"
+    return "sfx · 音效"
+
+
+def build_sidecar_payload(
+    *,
+    audio_path: Path,
+    label: str,
+    audio_type: str,
+    duration: float,
+    mode: str,
+    role: str | None,
+    strokes: list | None = None,
+    spectrogram_score: str | None = None,
+) -> dict:
+    resolved_role = (role or infer_role(label, audio_type)).strip()
+    payload = {
+        "kind": "playcraft.placeholder.audio",
+        "version": SIDECAR_VERSION,
+        "label": label,
+        "role": resolved_role,
+        "purpose": role_short(resolved_role),
+        "type": audio_type,
+        "durationSec": duration,
+        "loop": audio_type == "bgm",
+        "mode": mode,
+        "format": "mp3",
+        "audio": audio_path.name,
+        "note": "Develop-stage spectral audio stub (ANS-style fingerprint). TA replaces MP3 at the same contract path.",
+    }
+    if mode == "spectral" and strokes is not None:
+        payload["spectral"] = {
+            "style": "ans-spectrogram",
+            "strokes": strokes_to_sidecar(strokes),
+        }
+    if spectrogram_score:
+        payload["spectrogramScore"] = Path(spectrogram_score).name
+    return payload
+
+
+def write_audio_sidecar(audio_path: Path, payload: dict) -> Path:
+    return write_placeholder_sidecar(audio_path, payload)
+
+
+def generate_mp3(
+    output: Path,
+    *,
+    duration: float,
+    mode: str,
+    label: str,
+    audio_type: str,
+    sample_rate: int = 44100,
+    bitrate: str = "64k",
+) -> tuple[list | None, str | None]:
+    ffmpeg = require_ffmpeg()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    strokes = None
+    score_path = None
+
+    if mode == "silent":
+        input_args = ["-f", "lavfi", "-i", f"anullsrc=r={sample_rate}:cl=mono", "-t", str(duration)]
+    elif mode == "tone":
+        input_args = [
+            "-f",
+            "lavfi",
+            "-i",
+            f"sine=frequency=440:sample_rate={sample_rate}:duration={duration}",
+        ]
+    else:
+        strokes = build_spectral_strokes(label, audio_type, duration)
+        expr = build_aevalsrc_expression(strokes, duration)
+        input_args = [
+            "-f",
+            "lavfi",
+            "-i",
+            f"aevalsrc='{expr}':sample_rate={sample_rate}:duration={duration}",
+        ]
+        score_path = spectrogram_score_path_for(str(output))
+        render_spectrogram_score_png(
+            label=label,
+            strokes=strokes,
+            duration=duration,
+            output_path=score_path,
+        )
+
+    cmd = [
+        ffmpeg,
+        "-y",
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        *input_args,
+        "-c:a",
+        "libmp3lame",
+        "-b:a",
+        bitrate,
+        str(output),
+    ]
+    subprocess.run(cmd, check=True)
+    return strokes, score_path
+
+
+def normalize_batch_entry(entry: dict) -> dict:
+    label = entry.get("label") or entry.get("text") or Path(str(entry.get("path", ""))).stem
+    audio_type = str(entry.get("type", "sfx")).lower()
+    if audio_type not in {"sfx", "bgm"}:
+        raise ValueError(f"invalid audio type: {audio_type}")
+    mode = str(entry.get("mode", "spectral")).lower()
+    if entry.get("tone"):
+        mode = "tone"
+    if mode not in VALID_MODES:
+        raise ValueError(f"invalid audio mode: {mode}")
+    return {
+        "path": str(normalize_output_path(str(entry["path"]))),
+        "label": str(label),
+        "type": audio_type,
+        "duration": entry.get("duration"),
+        "mode": mode,
+        "role": (str(entry["role"]).strip() or None) if entry.get("role") is not None else None,
+    }
+
+
+def generate_one(
+    *,
+    output: str,
+    label: str | None,
+    audio_type: str,
+    duration: float | None,
+    mode: str,
+    role: str | None,
+    dry_run: bool = False,
+) -> dict:
+    output_path = normalize_output_path(output)
+    output_str = str(output_path)
+    resolved_label = label or output_path.stem
+    resolved_duration = default_duration(audio_type, duration)
+    sidecar_str = str(sidecar_path_for(output_path))
+    score_str = spectrogram_score_path_for(output_str) if mode == "spectral" else None
+
+    if dry_run:
+        return {
+            "path": output_str,
+            "sidecar": sidecar_str,
+            "spectrogramScore": score_str,
+            "label": resolved_label,
+            "type": audio_type,
+            "mode": mode,
+            "durationSec": resolved_duration,
+            "dry_run": True,
+        }
+
+    strokes, score_path = generate_mp3(
+        output_path,
+        duration=resolved_duration,
+        mode=mode,
+        label=resolved_label,
+        audio_type=audio_type,
+    )
+    payload = build_sidecar_payload(
+        audio_path=output_path,
+        label=resolved_label,
+        audio_type=audio_type,
+        duration=resolved_duration,
+        mode=mode,
+        role=role,
+        strokes=strokes,
+        spectrogram_score=score_path,
+    )
+    write_audio_sidecar(output_path, payload)
+    return {
+        "path": output_str,
+        "sidecar": sidecar_str,
+        "sidecarData": payload,
+        "spectrogramScore": score_path,
+        "label": resolved_label,
+        "type": audio_type,
+        "mode": mode,
+        "durationSec": resolved_duration,
+        "ok": True,
+    }
+
+
+def run_batch(batch_path: Path, *, dry_run: bool = False) -> list[dict]:
+    rows = json.loads(batch_path.read_text(encoding="utf-8"))
+    if not isinstance(rows, list):
+        raise ValueError("batch file must be a JSON array")
+    results: list[dict] = []
+    for raw in rows:
+        entry = normalize_batch_entry(raw)
+        results.append(
+            generate_one(
+                output=entry["path"],
+                label=entry["label"],
+                audio_type=entry["type"],
+                duration=entry["duration"],
+                mode=entry["mode"],
+                role=entry.get("role"),
+                dry_run=dry_run,
+            )
+        )
+    return results
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Generate develop-stage audio placeholders (spectral / silent / tone). "
+            "Always writes a same-stem .json sidecar beside each .mp3."
+        )
+    )
+    parser.add_argument("-o", "--output", help="Output .mp3 path")
+    parser.add_argument("--label", help="Asset label / elementId (defaults to output stem)")
+    parser.add_argument("--role", help="Purpose for TA handoff")
+    parser.add_argument("--type", default="sfx", choices=["sfx", "bgm"], help="sfx=short stub, bgm=longer stub")
+    parser.add_argument("--duration", type=float, help="Duration in seconds (overrides type default)")
+    parser.add_argument(
+        "--mode",
+        default="spectral",
+        choices=sorted(VALID_MODES),
+        help="spectral=ANS-style fingerprint from label (default); silent; tone",
+    )
+    parser.add_argument("--tone", action="store_true", help="Alias for --mode tone")
+    parser.add_argument("--silent", action="store_true", help="Alias for --mode silent")
+    parser.add_argument("--batch", type=Path, help="JSON array of audio placeholder rows")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--json", action="store_true", help="Emit run summary JSON to stdout (sidecar files are always written)")
+    return parser
+
+
+def resolve_mode(args: argparse.Namespace) -> str:
+    if args.tone:
+        return "tone"
+    if args.silent:
+        return "silent"
+    return args.mode
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+    mode = resolve_mode(args)
+
+    try:
+        if args.batch:
+            results = run_batch(args.batch, dry_run=args.dry_run)
+            if args.json:
+                print(json.dumps({"ok": True, "count": len(results), "items": results}, ensure_ascii=False))
+            else:
+                for item in results:
+                    prefix = "DRY" if args.dry_run else "OK"
+                    extra = f" + {item['spectrogramScore']}" if item.get("spectrogramScore") else ""
+                    print(
+                        f"[{prefix}] {item['path']} + {item['sidecar']}{extra} "
+                        f"({item['type']}, mode={item['mode']}, {item['durationSec']}s)"
+                    )
+            return 0
+
+        if not args.output:
+            parser.error("--output is required unless --batch is provided")
+
+        result = generate_one(
+            output=args.output,
+            label=args.label,
+            audio_type=args.type,
+            duration=args.duration,
+            mode=mode,
+            role=args.role,
+            dry_run=args.dry_run,
+        )
+        if args.json:
+            print(json.dumps({"ok": True, "item": result}, ensure_ascii=False))
+        else:
+            prefix = "DRY" if args.dry_run else "OK"
+            extra = f" + {result['spectrogramScore']}" if result.get("spectrogramScore") else ""
+            print(
+                f"[{prefix}] {result['path']} + {result['sidecar']}{extra} "
+                f"({result['type']}, mode={result['mode']}, {result['durationSec']}s)"
+            )
+        return 0
+    except Exception as exc:  # noqa: BLE001
+        if args.json:
+            print(json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False))
+        else:
+            print(f"[gen-placeholder-audio] ERROR: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/project-template/skills/_shared/scripts/gen-placeholder.py

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""Generate local placeholder images for develop-stage asset materialization.
+
+Replaces placehold.co with offline generation, richer shape support, and batch mode.
+
+Examples:
+  python3 skills/_shared/scripts/gen-placeholder.py \\
+    -o assets/images/tiles/tile_gold.webp --size 128x128 \\
+    --bg ffcc00 --fg 000000 --text tile_gold --shape circle
+
+  npm run placeholder:gen -- --batch ta-workspace/placeholders.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+from placeholder_lib import (  # noqa: E402
+    build_sidecar_payload,
+    infer_shape,
+    normalize_batch_entry,
+    normalize_output_path,
+    parse_size,
+    render_placeholder,
+    resolve_transparent_bg,
+    save_placeholder,
+    sidecar_path_for,
+    write_placeholder_sidecar,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Generate local placeholder images. Always writes a same-stem .json sidecar beside each image."
+    )
+    parser.add_argument("-o", "--output", help="Output file path")
+    parser.add_argument("--size", default="128x128", help="WxH or square size, e.g. 300x100 or 128")
+    parser.add_argument(
+        "--bg",
+        default="1a1a2e",
+        help="Background fill: hex/CSS name, or gradient "
+        "(linear:ffcc00→ff9900[:vertical|horizontal], radial:fff@center→transparent@edge)",
+    )
+    parser.add_argument("--fg", default="cccccc", help="Foreground/text color")
+    parser.add_argument("--text", help="Center label / elementId (defaults to output stem)")
+    parser.add_argument("--role", help="Asset purpose for TA handoff, e.g. 'CTA button · 主按钮'")
+    parser.add_argument(
+        "--shape",
+        default="auto",
+        choices=[
+            "auto",
+            "fill",
+            "rounded",
+            "circle",
+            "ellipse",
+            "diamond",
+            "ring",
+            "triangle-up",
+            "triangle-down",
+        ],
+        help="Placeholder shape; auto infers from label + aspect ratio",
+    )
+    parser.add_argument("--retina", type=int, default=1, choices=[1, 2, 3], help="Scale factor")
+    parser.add_argument("--batch", type=Path, help="JSON array of placeholder rows")
+    parser.add_argument(
+        "--transparent",
+        action="store_true",
+        help="Force transparent canvas outside shape (default for non-fill shapes)",
+    )
+    parser.add_argument(
+        "--opaque",
+        action="store_true",
+        help="Force opaque canvas (fill entire image with bg color)",
+    )
+    parser.add_argument("--minimal", action="store_true", help="Force 2-line compact metadata layout")
+    parser.add_argument("--dry-run", action="store_true", help="Print actions without writing files")
+    parser.add_argument("--json", action="store_true", help="Emit run summary JSON to stdout (sidecar files are always written)")
+    return parser
+
+
+def generate_one(
+    *,
+    output: str,
+    size: str,
+    bg: str,
+    fg: str,
+    text: str | None,
+    role: str | None,
+    shape: str,
+    retina: int,
+    minimal: bool = False,
+    transparent_bg: bool | None = None,
+    dry_run: bool = False,
+) -> dict:
+    output_path = normalize_output_path(output)
+    output_str = str(output_path)
+    logical_width, logical_height = parse_size(size)
+    width = logical_width * retina
+    height = logical_height * retina
+    label = text or output_path.stem
+    resolved_shape = infer_shape(label, width, height) if shape == "auto" else shape
+    transparent = resolve_transparent_bg(resolved_shape, transparent_bg)
+    sidecar_str = str(sidecar_path_for(output_path))
+
+    if dry_run:
+        return {
+            "path": output_str,
+            "sidecar": sidecar_str,
+            "size": f"{width}x{height}",
+            "shape": resolved_shape,
+            "label": label,
+            "format": output_path.suffix.lstrip(".") or "webp",
+            "dry_run": True,
+        }
+
+    image = render_placeholder(
+        width=width,
+        height=height,
+        bg=bg,
+        fg=fg,
+        text=label,
+        role=role,
+        minimal=minimal,
+        transparent_bg=transparent_bg,
+        shape=resolved_shape,  # type: ignore[arg-type]
+    )
+    save_placeholder(image, output_str)
+    sidecar_payload = build_sidecar_payload(
+        image_path=output_str,
+        label=label,
+        width=width,
+        height=height,
+        bg=bg,
+        fg=fg,
+        shape=resolved_shape,
+        role=role,
+        transparent=transparent,
+        retina=retina,
+        logical_width=logical_width,
+        logical_height=logical_height,
+    )
+    write_placeholder_sidecar(output_str, sidecar_payload)
+    return {
+        "path": output_str,
+        "sidecar": sidecar_str,
+        "sidecarData": sidecar_payload,
+        "size": f"{width}x{height}",
+        "shape": resolved_shape,
+        "label": label,
+        "format": output_path.suffix.lstrip(".") or "webp",
+        "ok": True,
+    }
+
+
+def run_batch(batch_path: Path, *, dry_run: bool = False) -> list[dict]:
+    rows = json.loads(batch_path.read_text(encoding="utf-8"))
+    if not isinstance(rows, list):
+        raise ValueError("batch file must be a JSON array")
+    results: list[dict] = []
+    for raw in rows:
+        entry = normalize_batch_entry(raw)
+        results.append(
+            generate_one(
+                output=entry["path"],
+                size=entry["size"],
+                bg=entry["bg"],
+                fg=entry["fg"],
+                text=entry["label"],
+                role=entry.get("role"),
+                minimal=entry.get("minimal", False),
+                transparent_bg=entry.get("transparent"),
+                shape=entry["shape"],
+                retina=entry["retina"],
+                dry_run=dry_run,
+            )
+        )
+    return results
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    try:
+        if args.batch:
+            results = run_batch(args.batch, dry_run=args.dry_run)
+            if args.json:
+                print(json.dumps({"ok": True, "count": len(results), "items": results}, ensure_ascii=False))
+            else:
+                for item in results:
+                    prefix = "DRY" if args.dry_run else "OK"
+                    print(
+                        f"[{prefix}] {item['path']} + {item['sidecar']} "
+                        f"({item['size']}, shape={item['shape']})"
+                    )
+            return 0
+
+        if not args.output:
+            parser.error("--output is required unless --batch is provided")
+
+        transparent_bg = None
+        if args.transparent:
+            transparent_bg = True
+        if args.opaque:
+            transparent_bg = False
+
+        result = generate_one(
+            output=args.output,
+            size=args.size,
+            bg=args.bg,
+            fg=args.fg,
+            text=args.text,
+            role=args.role,
+            minimal=args.minimal,
+            transparent_bg=transparent_bg,
+            shape=args.shape,
+            retina=args.retina,
+            dry_run=args.dry_run,
+        )
+        if args.json:
+            print(json.dumps({"ok": True, "item": result}, ensure_ascii=False))
+        else:
+            prefix = "DRY" if args.dry_run else "OK"
+            print(
+                f"[{prefix}] {result['path']} + {result['sidecar']} "
+                f"({result['size']}, shape={result['shape']})"
+            )
+        return 0
+    except Exception as exc:  # noqa: BLE001
+        if args.json:
+            print(json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False))
+        else:
+            print(f"[gen-placeholder] ERROR: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())