dsh-drawai 0.3.4 → 0.4.0

package/lib/motion/shotcraft/upstream/assets/scripts/capture-template.mjs

@@ -0,0 +1,210 @@
+// capture-template.mjs — 把真实产品页面变成宣传片素材的三件套采集脚本模板
+// 通用页面截图管线模板：BASE/输出目录/路由/选择器全部提升为 CONFIG
+//
+// 产出三件套（宣传片 3D 页面平面的全部素材来源）：
+//   1. 每个路由的全页 2x 截图（deviceScaleFactor: 2，供 3D 场景贴图不糊）
+//   2. per-element cutout（元素级 PNG，含 omitBackground 透明抠图，供"浮起的 UI 芯片"）
+//   3. layout.json（每个元素在整页坐标系里的 bbox，供动画按真实版式定位）
+//
+// 用法：
+//   node capture-template.mjs
+//
+// 前置条件（三条都是硬前提）：
+//   1. 目标产品在本地跑起来（CONFIG.BASE 可访问）；
+//   2. npm i puppeteer（本脚本唯一依赖）；
+//   3. 【红线】假数据先注入 —— 截图前页面必须已填充"虚构但真实感"的演示数据。
+//      空库/lorem ipsum 截出来的图直接废片；真实客户数据则不能出片。
+//      先做数据注入（seed 脚本 / fixture 环境），确认页面肉眼可看后再跑本脚本。
+//
+// 改造指南：只改下面的 CONFIG。每个 page 条目 = 一个路由；
+// boxes 只记坐标（进 layout.json），cutouts 记坐标 + 存元素 PNG。
+
+import puppeteer from 'puppeteer';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// ======================================================================
+// CONFIG — 按目标产品修改（下面的值是假想的 "acme-crm" 产品示例）
+// ======================================================================
+const CONFIG = {
+  // 目标产品本地地址（先把产品跑起来）
+  BASE: 'http://localhost:3000',
+
+  // 截图与 layout.json 的输出目录（相对本脚本所在目录；通常指向
+  // Remotion 项目的 public/textures/live，供 staticFile() 引用）
+  OUT_DIR: '../../public/textures/live',
+  LAYOUT_JSON: '../../src/live-layout.json',
+
+  // 视口：1920x1080 @2x 是 3D 页面平面贴图的经验值
+  VIEWPORT: { width: 1920, height: 1080, deviceScaleFactor: 2 },
+
+  // 每页导航完成后的额外静置毫秒数（等字体/异步数据；见 settle()）
+  SETTLE_MS: 600,
+
+  // 路由清单：每条 = 一个要采集的页面
+  PAGES: [
+    {
+      name: 'home',                 // layout.json 里的 key，也是全页截图文件名前缀
+      path: '/',                    // 相对 BASE 的路由
+      // waitMs: 1500,              // 可选：本页额外等待（如实时协作数据同步）
+      // 只记坐标不出图的元素（进 layout.<name>.boxes.<key>）
+      boxes: [
+        // all: true → 记所有匹配元素的 bbox 数组；否则只记第一个
+        { key: 'sections', selector: 'main h2', all: true },
+      ],
+      // 元素级截图（cutout PNG + bbox）。omitBackground: true 出透明底，
+      // 用于要"浮"在页面平面上方、自带材质合成的 UI 芯片
+      cutouts: [
+        { name: 'nav', selector: 'header, [role="banner"]' },
+        { name: 'card', selector: 'article', all: true, max: 12 },       // card1.png, card2.png…
+        { name: 'float-search', selector: 'input', parent: true, omitBackground: true },
+        { name: 'float-filter', selector: 'main button', omitBackground: true },
+      ],
+      // 可选：把某些元素设为 visibility:hidden 后再截一张全页图，
+      // 作为"元素飞入"镜头的空底板（<name>-empty.png）
+      hideForEmptyPlate: 'article',
+    },
+    {
+      name: 'detail',
+      // 详情页路由写死一条演示数据的 id（假想示例；换成你产品里
+      // 注入的假数据实体 id）
+      path: '/customers/demo-0001',
+      boxes: [
+        { key: 'rows', selector: 'table tbody tr, [role="row"]', all: true, max: 8 },
+      ],
+      cutouts: [],
+      // 可选：截图前在页面里执行的交互（如点开某个 tab），
+      // 返回后额外等 interactWaitMs 再补一张 <name>-after.png 全页图
+      interact: () => {
+        const tab = [...document.querySelectorAll('button, [role="tab"], a')]
+          .find((e) => /订单/.test(e.textContent ?? ''));
+        if (tab) { tab.click(); return true; }
+        return false;
+      },
+      interactWaitMs: 800,
+    },
+    {
+      name: 'reports',
+      path: '/reports/weekly',
+      waitMs: 1500, // 例：等编辑器/协作文档内容同步进来
+      boxes: [
+        { key: 'paras', selector: '.ProseMirror > p', all: true },
+      ],
+      cutouts: [],
+    },
+  ],
+};
+// ======================================================================
+// 以下为通用采集逻辑，一般无需修改
+// ======================================================================
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const outDir = path.resolve(here, CONFIG.OUT_DIR);
+const layoutPath = path.resolve(here, CONFIG.LAYOUT_JSON);
+fs.mkdirSync(outDir, { recursive: true });
+fs.mkdirSync(path.dirname(layoutPath), { recursive: true });
+
+const browser = await puppeteer.launch();
+const page = await browser.newPage();
+await page.setViewport(CONFIG.VIEWPORT);
+
+// 等字体加载完再静置片刻——避免截到 FOUT/骨架屏
+const settle = async () => {
+  await page.evaluate(() => document.fonts.ready);
+  await new Promise((r) => setTimeout(r, CONFIG.SETTLE_MS));
+};
+
+// 元素 bbox 换算到整页坐标系（fullPage 截图的坐标系）
+const pageBox = (el) =>
+  el.evaluate((e) => {
+    const r = e.getBoundingClientRect();
+    return { x: r.x + window.scrollX, y: r.y + window.scrollY, w: r.width, h: r.height };
+  });
+
+const layout = { pageW: CONFIG.VIEWPORT.width };
+
+for (const pg of CONFIG.PAGES) {
+  await page.goto(`${CONFIG.BASE}${pg.path}`, { waitUntil: 'networkidle0' });
+  await settle();
+  if (pg.waitMs) await new Promise((r) => setTimeout(r, pg.waitMs));
+
+  const entry = { pageH: await page.evaluate(() => document.documentElement.scrollHeight) };
+  layout[pg.name] = entry;
+
+  // ---- 1. 全页 2x 截图 ----
+  await page.screenshot({ path: `${outDir}/${pg.name}-full.png`, fullPage: true });
+  console.log(`captured ${pg.name}-full`, entry.pageH);
+
+  // ---- 2. boxes：只记坐标 ----
+  entry.boxes = {};
+  for (const b of pg.boxes ?? []) {
+    const els = await page.$$(b.selector);
+    const picked = b.all ? els.slice(0, b.max ?? els.length) : els.slice(0, 1);
+    const boxes = [];
+    for (const el of picked) boxes.push(await pageBox(el));
+    entry.boxes[b.key] = b.all ? boxes : boxes[0] ?? null;
+    console.log(`  boxes.${b.key}:`, boxes.length);
+  }
+
+  // ---- 3. cutouts：元素 PNG + bbox ----
+  entry.cutouts = [];
+  for (const c of pg.cutouts ?? []) {
+    let els = await page.$$(c.selector);
+    if (c.parent) {
+      // 取匹配元素的父容器（如 input 的圆角外壳）
+      const parents = [];
+      for (const el of els) {
+        const h = await el.evaluateHandle((e) => e.parentElement);
+        const p = h.asElement();
+        if (p) parents.push(p);
+      }
+      els = parents;
+    }
+    const picked = c.all ? els.slice(0, c.max ?? els.length) : els.slice(0, 1);
+    for (let i = 0; i < picked.length; i++) {
+      const file = c.all ? `${c.name}${i + 1}.png` : `${c.name}.png`;
+      const bb = await pageBox(picked[i]);
+      try {
+        await picked[i].screenshot({
+          path: `${outDir}/${file}`,
+          omitBackground: !!c.omitBackground,
+        });
+      } catch (e) {
+        console.log(`  cutout miss ${file}:`, e.message);
+        continue;
+      }
+      entry.cutouts.push({ file, ...bb });
+      console.log(`  captured ${file}`, bb);
+    }
+    if (picked.length === 0) console.log(`  cutout miss ${c.name} (no match: ${c.selector})`);
+  }
+
+  // ---- 4. 页内交互后的补充全页图（可选） ----
+  if (pg.interact) {
+    const did = await page.evaluate(pg.interact);
+    if (did) {
+      await new Promise((r) => setTimeout(r, pg.interactWaitMs ?? 800));
+      await page.screenshot({ path: `${outDir}/${pg.name}-after.png`, fullPage: true });
+      entry.afterPageH = await page.evaluate(() => document.documentElement.scrollHeight);
+      console.log(`captured ${pg.name}-after`);
+    }
+  }
+
+  // ---- 5. 空底板（可选）：隐藏元素后再截一张，供飞入镜头 ----
+  if (pg.hideForEmptyPlate) {
+    await page.evaluate((sel) => {
+      document.querySelectorAll(sel).forEach((el) => { el.style.visibility = 'hidden'; });
+    }, pg.hideForEmptyPlate);
+    await page.screenshot({ path: `${outDir}/${pg.name}-empty.png`, fullPage: true });
+    console.log(`captured ${pg.name}-empty`);
+    // 复原，避免影响同页后续步骤（当前实现里本步骤已是该页最后一步）
+    await page.evaluate((sel) => {
+      document.querySelectorAll(sel).forEach((el) => { el.style.visibility = ''; });
+    }, pg.hideForEmptyPlate);
+  }
+}
+
+fs.writeFileSync(layoutPath, JSON.stringify(layout, null, 1));
+console.log('wrote', layoutPath);
+await browser.close();

package/lib/motion/shotcraft/upstream/assets/scripts/sfx-source.py

@@ -0,0 +1,423 @@
+#!/usr/bin/env python3
+"""Find Freesound SFX and freeze licensed MP3 previews in a video project.
+
+Python standard library; get/analyze also require ffmpeg and ffprobe.
+No API key, global cache, login, or proxy configuration changes.
+"""
+
+import argparse
+import array
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime, timezone
+import hashlib
+from html.parser import HTMLParser
+import json
+import math
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from urllib.parse import unquote, urlencode, urljoin, urlparse
+from urllib.request import Request, urlopen
+
+
+SITE = "https://freesound.org"
+MANIFEST = "audio-manifest.json"
+CREDITS = "FREESOUND-CREDITS.md"
+MAX_BYTES = 32 * 1024 * 1024
+VOID = set("area base br col embed hr img input link meta param source track wbr".split())
+
+
+class Node:
+    def __init__(self, tag="root", attrs=()):
+        self.tag, self.attrs, self.children = tag, dict(attrs), []
+
+    def nodes(self):
+        yield self
+        for child in self.children:
+            if isinstance(child, Node):
+                yield from child.nodes()
+
+    def text(self):
+        return " ".join(c.text() if isinstance(c, Node) else c for c in self.children).strip()
+
+    def has_class(self, name):
+        return name in self.attrs.get("class", "").split()
+
+
+class Document(HTMLParser):
+    def __init__(self, content):
+        super().__init__(convert_charrefs=True)
+        self.root = Node()
+        self.stack = [self.root]
+        self.feed(content)
+        self.close()
+
+    def handle_starttag(self, tag, attrs):
+        node = Node(tag, attrs)
+        self.stack[-1].children.append(node)
+        if tag not in VOID:
+            self.stack.append(node)
+
+    def handle_startendtag(self, tag, attrs):
+        self.handle_starttag(tag, attrs)
+        if tag not in VOID:
+            self.handle_endtag(tag)
+
+    def handle_endtag(self, tag):
+        for i in range(len(self.stack) - 1, 0, -1):
+            if self.stack[i].tag == tag:
+                del self.stack[i:]
+                break
+
+    def handle_data(self, data):
+        self.stack[-1].children.append(data)
+
+
+def request(url):
+    req = Request(url, headers={"User-Agent": "video-shotcraft/1.0 (Freesound SFX sourcing)"})
+    with urlopen(req, timeout=30) as response:
+        data = response.read(MAX_BYTES + 1)
+        if len(data) > MAX_BYTES:
+            raise ValueError("Response exceeds 32 MiB; select a shorter sound or download the original manually")
+        return data, response.geturl(), response.headers.get_content_type()
+
+
+def web_page(url):
+    data, final_url, content_type = request(url)
+    if urlparse(final_url).hostname != "freesound.org" or content_type != "text/html":
+        raise ValueError("Expected a Freesound HTML page")
+    return Document(data.decode("utf-8")), final_url
+
+
+def sound_id(value):
+    value = value.removeprefix("fs:")
+    if not re.fullmatch(r"[1-9][0-9]*", value):
+        raise ValueError(f"Invalid Freesound ID: {value!r}; use fs:12345")
+    return value
+
+
+def license_code(url):
+    parsed = urlparse(url)
+    if parsed.scheme not in {"http", "https"} or parsed.hostname not in {"creativecommons.org", "www.creativecommons.org"}:
+        return None
+    path = parsed.path.rstrip("/")
+    if path == "/publicdomain/zero/1.0":
+        return "CC0-1.0"
+    match = re.fullmatch(r"/licenses/by/(1\.0|2\.0|2\.5|3\.0|4\.0)", path)
+    return f"CC-BY-{match[1]}" if match else None
+
+
+def check_license(code, policy):
+    if policy == "any":
+        return
+    if code == "CC0-1.0" or (policy == "by" and code and code.startswith("CC-BY-")):
+        return
+    raise ValueError(f"License {code or 'unknown'} is outside --license {policy}; CC BY requires --license by")
+
+
+def player_data(node, page_author=None):
+    attrs = node.attrs
+    sid = sound_id(attrs["data-sound-id"])
+    title, author = attrs.get("data-title"), page_author or attrs.get("data-username")
+    duration = float(attrs["data-duration"])
+    if not title or not author or not math.isfinite(duration) or duration <= 0:
+        raise ValueError(f"Incomplete Freesound metadata for fs:{sid}")
+    preview = attrs.get("data-mp3", "")
+    parsed = urlparse(preview)
+    if (parsed.scheme != "https" or parsed.hostname != "cdn.freesound.org"
+            or not re.fullmatch(rf"/previews/[0-9]+/{sid}_[0-9]+-(lq|hq)\.mp3", parsed.path)):
+        raise ValueError(f"Missing or unexpected preview URL for fs:{sid}")
+    return {"id": f"fs:{sid}", "title": title, "author": author,
+            "duration_seconds": duration, "preview_url": preview.replace("-lq.mp3", "-hq.mp3"),
+            "downloads": int(attrs.get("data-num-downloads") or 0)}
+
+
+def stats(nodes):
+    rating, count = None, None
+    for node in nodes:
+        label = node.attrs.get("aria-label", "")
+        if label.startswith("Average rating of "):
+            rating = float(label.removeprefix("Average rating of "))
+        if node.has_class("bw-rating__count"):
+            found = re.search(r"\(([0-9]+)(?: ratings?)?\)", node.text())
+            if found:
+                count = int(found[1])
+    return {"rating": rating, "rating_count": count}
+
+
+def parse_search(doc):
+    rows = []
+    for block in doc.root.nodes():
+        if not block.has_class("bw-search__result"):
+            continue
+        nodes = list(block.nodes())
+        player = next((n for n in nodes if n.attrs.get("data-sound-id")), None)
+        if player is None:
+            raise ValueError("Freesound search markup changed: result has no sound metadata")
+        row = player_data(player)
+        links = [urljoin(SITE, n.attrs.get("href", "")) for n in nodes if n.tag == "a"]
+        row["page_url"] = next((u for u in links if u.endswith(f"/sounds/{sound_id(row['id'])}/")), None)
+        row["license_label"] = next((n.attrs["title"][9:] for n in nodes
+                                     if n.attrs.get("title", "").startswith("License: ")), "unknown")
+        desc = next((n for n in nodes if any(c.startswith("max-h-60px")
+                     for c in n.attrs.get("class", "").split())), None)
+        row["description"] = " ".join((desc.attrs.get("title") or desc.text()).split()) if desc else ""
+        row.update(stats(nodes))
+        rows.append(row)
+    if not rows and not re.search(r"no (?:sounds|results)|0 sounds|couldn't find|did not match", doc.root.text(), re.I):
+        raise ValueError("No recognizable search results; check Freesound availability or update the parser")
+    return rows
+
+
+def search(args):
+    if args.license == "any":
+        labels = None
+        filters = []
+    else:
+        labels = {"Creative Commons 0"} | ({"Attribution"} if args.license == "by" else set())
+        filters = ['license:("Creative Commons 0" OR "Attribution")' if args.license == "by"
+                   else 'license:"Creative Commons 0"']
+    filters.append(f"duration:[{args.min_duration} TO {args.max_duration if args.max_duration is not None else '*'}]")
+    found = {}
+    for page in range(1, args.pages + 1):
+        query = urlencode({"q": args.query, "f": " ".join(filters), "page": page, "s": "Automatic by relevance"})
+        doc, _ = web_page(f"{SITE}/search/?{query}")
+        for row in parse_search(doc):
+            # Enforce locally too; never trust a server-side filter alone.
+            if labels is not None and row["license_label"] not in labels:
+                continue
+            if row["duration_seconds"] < args.min_duration:
+                continue
+            if args.max_duration is not None and row["duration_seconds"] > args.max_duration:
+                continue
+            found.setdefault(row["id"], row)
+    result = {"provider": "freesound", "query": args.query, "license_policy": args.license,
+              "ordering": "relevance; popularity is supporting evidence only",
+              "results": list(found.values())[:args.limit]}
+    emit(result, args.output)
+    return 0
+
+
+def detail(sid):
+    doc, final_url = web_page(f"{SITE}/s/{sid}/")
+    nodes = list(doc.root.nodes())
+    player = next((n for n in nodes if n.attrs.get("data-sound-id") == sid and n.attrs.get("data-mp3")), None)
+    canonical = re.fullmatch(rf"/people/([^/]+)/sounds/{sid}/", urlparse(final_url).path)
+    if player is None or canonical is None:
+        raise ValueError(f"Missing canonical sound page for fs:{sid}")
+    # Large players omit data-username; the canonical page supplies the creator.
+    row = player_data(player, unquote(canonical[1]))
+    row["page_url"] = final_url
+    licenses = {n.attrs["href"] for n in nodes if n.tag == "a"
+                and urlparse(n.attrs.get("href", "")).hostname in {"creativecommons.org", "www.creativecommons.org"}}
+    if len(licenses) != 1:
+        raise ValueError(f"Missing or ambiguous license on fs:{sid}")
+    row["license_url"] = licenses.pop()
+    row["license"] = license_code(row["license_url"])
+    row["description"] = next((n.attrs.get("content", "") for n in nodes
+                               if n.attrs.get("name") == "twitter:description"), "")
+    row.update(stats(nodes))
+    return row
+
+
+def require_audio_tools():
+    if not all(shutil.which(name) for name in ("ffmpeg", "ffprobe")):
+        raise ValueError("get/analyze require ffmpeg and ffprobe on PATH")
+
+
+def analyze(path):
+    require_audio_tools()
+    path = Path(path).resolve()
+    probe = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "a:0", "-show_entries",
+                            "stream=codec_name,sample_rate,channels:format=duration", "-of", "json", str(path)],
+                           capture_output=True, text=True, check=True)
+    info = json.loads(probe.stdout)
+    stream = info["streams"][0]
+    channels = int(stream["channels"])
+    if not 1 <= channels <= 8:
+        raise ValueError("Expected an audio file with 1–8 channels")
+    rate, window = 48000, 0.01
+    block_size = int(rate * window) * channels * 4
+    energies, peak, squares, samples = [], 0.0, 0.0, 0
+    # Preserve channels: downmixing first can hide opposite-polarity peaks.
+    with tempfile.TemporaryFile() as errors:
+        with subprocess.Popen(["ffmpeg", "-v", "error", "-i", str(path), "-map", "0:a:0", "-ar", str(rate),
+                               "-f", "f32le", "-acodec", "pcm_f32le", "pipe:1"],
+                              stdout=subprocess.PIPE, stderr=errors) as process:
+            while True:
+                raw = process.stdout.read(block_size)
+                if not raw:
+                    break
+                values = array.array("f")
+                values.frombytes(raw)
+                if sys.byteorder != "little":
+                    values.byteswap()
+                energy = sum(v * v for v in values)
+                energies.append(math.sqrt(energy / len(values)))
+                peak = max(peak, max(abs(v) for v in values))
+                squares += energy
+                samples += len(values)
+            if process.wait() != 0:
+                errors.seek(0)
+                raise ValueError(errors.read().decode("utf-8", errors="replace"))
+    if not samples or not peak:
+        raise ValueError("Audio is empty or silent")
+    loudest = max(energies)
+    active = [i for i, e in enumerate(energies) if e >= loudest * 0.01]
+    duration = samples / (rate * channels)
+    return {"codec": stream["codec_name"], "sample_rate": int(stream["sample_rate"]), "channels": channels,
+            "duration_seconds": round(duration, 6), "sample_peak_dbfs": round(20 * math.log10(peak), 3),
+            "rms_dbfs": round(20 * math.log10(math.sqrt(squares / samples)), 3),
+            "energy_window_seconds": window,
+            "energy_peak_seconds": round(min(duration, (energies.index(loudest) + 0.5) * window), 6),
+            "active_start_seconds": round(active[0] * window, 6),
+            "active_end_seconds": round(min(duration, (active[-1] + 1) * window), 6),
+            "activity_threshold_db_below_peak_rms": -40}
+
+
+def write_json(path, data):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", dir=path.parent, delete=False) as tmp:
+        json.dump(data, tmp, ensure_ascii=False, indent=2, allow_nan=False)
+        tmp.write("\n")
+    Path(tmp.name).replace(path)
+
+
+def emit(data, output=None):
+    if output:
+        write_json(output, data)
+    print(json.dumps(data, ensure_ascii=False, indent=2, allow_nan=False))
+
+
+def digest(path):
+    return hashlib.sha256(Path(path).read_bytes()).hexdigest()
+
+
+def write_credits(out, rows):
+    # Plain text inside a fence keeps uploaded titles from becoming Markdown links/instructions.
+    lines = ["# Freesound audio credits", "", "Generated from audio-manifest.json; preserve with the video.", "",
+             "CC BY entries require attribution in the published video's credits/description.", "",
+             "Downloaded files are lossy MP3 previews, not uploader originals.", ""]
+    for row in rows:
+        lines += ["~~~text", f"{row['file']} — {row['title']} by {row['author']}".replace("~", "\\~"),
+                  row["page_url"], f"{row['license']}: {row['license_url']}",
+                  "Edits: " + ("; ".join(row.get("changes", [])) or "None recorded; update if edited."), "~~~", ""]
+    (out / CREDITS).write_text("\n".join(lines), encoding="utf-8")
+
+
+def download_one(sid, out, policy, existing):
+    row = detail(sid)  # Refresh the actual license, even when search/cache metadata is stale.
+    check_license(row["license"], policy)
+    dst = out / f"fs-{sid}.mp3"
+    old = next((r for r in existing if r["id"] == row["id"]), None)
+    if dst.exists():
+        if old is None or old.get("file") != dst.name or digest(dst) != old.get("sha256"):
+            raise ValueError(f"Refusing to overwrite untracked/modified file: {dst}")
+        return {**old, **row, "analysis": analyze(dst), "license_checked_at": datetime.now(timezone.utc).isoformat()}
+    payload, final_url, mime = request(row["preview_url"])
+    if urlparse(final_url).hostname != "cdn.freesound.org" or mime not in {"audio/mpeg", "audio/mp3", "application/octet-stream"}:
+        raise ValueError("Expected a Freesound MP3 preview, not an HTML error page")
+    with tempfile.NamedTemporaryFile(dir=out, suffix=".mp3", delete=False) as tmp:
+        tmp.write(payload)
+        tmp_path = Path(tmp.name)
+    try:
+        measurements = analyze(tmp_path)  # Decode successfully before admitting the file.
+        if measurements["codec"] != "mp3":
+            raise ValueError("Preview is not MP3 audio")
+        row.update({"provider": "freesound", "file": dst.name, "sha256": digest(tmp_path),
+                    "download_url": final_url, "download_kind": "mp3-preview-hq", "is_preview": True,
+                    "downloaded_at": datetime.now(timezone.utc).isoformat(),
+                    "license_checked_at": datetime.now(timezone.utc).isoformat(), "changes": [], "analysis": measurements})
+        # Exclusive creation: another process/user's file is never replaced.
+        with dst.open("xb") as target:
+            target.write(payload)
+        return row
+    finally:
+        tmp_path.unlink(missing_ok=True)
+
+
+def get(args):
+    require_audio_tools()
+    ids = list(dict.fromkeys(sound_id(value) for value in args.ids))
+    out = Path(args.out_dir).resolve()
+    out.mkdir(parents=True, exist_ok=True)
+    lock = out / ".freesound-download.lock"
+    try:
+        handle = lock.open("x")
+    except FileExistsError:
+        raise ValueError(f"Download already active in {out}; remove {lock.name} only if a previous run crashed")
+    try:
+        with handle:
+            return get_locked(args, ids, out)
+    finally:
+        lock.unlink(missing_ok=True)
+
+
+def get_locked(args, ids, out):
+    manifest_path = out / MANIFEST
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8")) if manifest_path.exists() else {"version": 1, "assets": []}
+    if manifest.get("version") != 1 or not isinstance(manifest.get("assets"), list):
+        raise ValueError("Unsupported audio manifest; use a separate output directory")
+    existing = manifest["assets"]
+
+    def run(sid):
+        try:
+            return {"ok": True, "asset": download_one(sid, out, args.license, existing)}
+        except (OSError, ValueError, KeyError, IndexError, subprocess.SubprocessError) as error:
+            return {"ok": False, "id": f"fs:{sid}", "error": str(error)}
+
+    results = []
+    with ThreadPoolExecutor(max_workers=args.workers) as pool:
+        for result in pool.map(run, ids):
+            results.append(result)
+            if result["ok"]:
+                row = result["asset"]
+                manifest["assets"] = [r for r in manifest["assets"] if r["id"] != row["id"]] + [row]
+                write_json(manifest_path, manifest)
+                write_credits(out, manifest["assets"])
+    emit({"out_dir": str(out), "results": results})
+    return 0 if all(r["ok"] for r in results) else 1
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    find = commands.add_parser("search", help="Search public Freesound pages; emit JSON candidates")
+    find.add_argument("query")
+    find.add_argument("--license", choices=("cc0", "by", "any"), default="any", help="any does not filter by license; by permits CC0 + CC BY")
+    find.add_argument("--min-duration", type=float, default=0)
+    find.add_argument("--max-duration", type=float)
+    find.add_argument("--limit", type=int, default=8)
+    find.add_argument("--pages", type=int, choices=range(1, 4), default=1)
+    find.add_argument("--output", help="Optional project-local JSON path")
+    fetch = commands.add_parser("get", help="Download IDs, verify licenses/audio, save manifest and credits")
+    fetch.add_argument("ids", nargs="+")
+    fetch.add_argument("--out-dir", required=True, help="Video project's public/audio/sfx directory")
+    fetch.add_argument("--license", choices=("cc0", "by", "any"), default="any")
+    fetch.add_argument("--workers", type=int, choices=range(1, 5), default=3)
+    measure = commands.add_parser("analyze", help="Measure decoded audio (10 ms RMS peak; not LUFS/true peak)")
+    measure.add_argument("file")
+    measure.add_argument("--output")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "search":
+            if not 1 <= args.limit <= 45 or not math.isfinite(args.min_duration) or args.min_duration < 0:
+                raise ValueError("Use --limit 1–45 and a nonnegative finite --min-duration")
+            if args.max_duration is not None and (not math.isfinite(args.max_duration) or args.max_duration <= args.min_duration):
+                raise ValueError("--max-duration must be finite and greater than --min-duration")
+            return search(args)
+        if args.command == "get":
+            return get(args)
+        emit(analyze(args.file), args.output)
+        return 0
+    except (OSError, ValueError, KeyError, IndexError, subprocess.SubprocessError) as error:
+        print(f"sfx-source: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())