@crievo/omni 0.0.0-stage → 0.1.0

package/tools/analysis.mjs

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+/* ============================================================================
+   What the metrics analysis reads, gathered in one place: the `av-analysis`
+   skill and the studio Analytics screen call this file, and both see the same
+   numbers.
+
+     node tools/analysis.mjs context               JSON: account, medians and each Reel with
+                                                  metrics, script strategy and hook
+     node tools/analysis.mjs frames videos/<slug> sheet of the published MP4's opening
+                                                  (0; 0.5; 1; 2; 3 s) → analysis/opening.png
+
+   The metrics come from `tools/metrics.mjs` (videos/<slug>/metrics.json and
+   .metrics/account.json). The medians are the channel's: on the `current`
+   reading (different ages, weak comparison) and on the 24 h and 72 h
+   milestones (same age, the comparison that counts). The readings series
+   (`instagram.hourly` in metrics.json) stays out of the context, which goes
+   whole to the UI and to the skill: only its count comes (`n_hourly`); whoever
+   needs it reads the video's metrics.json. Pillar, goal and hook come from the
+   Strategy and Hooks of script.md (skill `av-script`); scripts older than
+   those go without.
+   The context also has the channel `progression`: one point per collection
+   pass (the agent, every 4 hours, or "Coletar agora") in the last 30 days, with the
+   sum of the Reels (views, comments, saves) built from the `hourly` series
+   (each Reel counts its last reading up to that instant; before it was
+   published, zero; between publishing and the first reading, the line between
+   the two) and the followers from the account reading; and the
+   `publications` that fall in that range. And `before`: the 3 s skip range
+   before OmniVideo, if the channel playbook says so.
+   Read only, except `frames`, which writes the sheet in the video dir.
+   ============================================================================ */
+
+import { readFileSync, existsSync, mkdirSync, readdirSync, statSync, rmSync } from "node:fs";
+import { join, resolve, basename } from "node:path";
+import { spawnSync } from "node:child_process";
+import { table, agentStatus } from "./metrics.mjs";
+import { isMainModule, DATA_ROOT as ROOT } from "./lib/paths.mjs";
+
+const CHANNEL = join(ROOT, "channel");
+const ANALYSES = join(CHANNEL, "analyses");
+const FRAMES = [0, 0.5, 1, 2, 3];
+/* what goes into the medians, and whether more is better (skip is the opposite) */
+export const METRICS = {
+  views: 1,
+  reach: 1,
+  skip_3s_pct: -1,
+  watched_pct: 1,
+  avg_watch_s: 1,
+  saves: 1,
+  shares: 1,
+  comments: 1,
+  likes: 1,
+  saves_per_k: 1,
+  shares_per_k: 1,
+  comments_per_k: 1,
+};
+/* per thousand views: compares Reels of different sizes */
+const perK = (n, views) => (n == null || !views ? null : Math.round((n / views) * 10000) / 10);
+const withPerK = f => ({
+  ...f,
+  saves_per_k: perK(f.saves, f.views),
+  shares_per_k: perK(f.shares, f.views),
+  comments_per_k: perK(f.comments, f.views),
+});
+const H = 3_600_000;
+
+const fail = msg => {
+  console.error(`erro: ${msg}`);
+  process.exit(1);
+};
+const readText = file => {
+  try {
+    return readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+};
+const readJson = file => {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+};
+
+/* a `| field | value |` row of a script.md table; the template text doesn't count */
+function cell(md, field) {
+  const m = new RegExp(`^\\|\\s*\\**${field}\\**\\s*\\|\\s*(.+?)\\s*\\|\\s*$`, "mi").exec(md);
+  const v = m?.[1]?.trim();
+  if (
+    !v ||
+    /^(um dos pilares|alcance · seguidor|a do objetivo|quem para de rolar|o que a pessoa leva|a dúvida que|o que o objetivo pede)/i.test(
+      v,
+    )
+  )
+    return null;
+  return v.replace(/\*\*/g, "");
+}
+
+/* the Strategy and the chosen hook of script.md (skill av-script); the labels are PT content */
+export function strategy(dir) {
+  const md = readText(join(dir, "script.md"));
+  if (!md) return { pillar: null, goal: null, promise: null, hook: null };
+  /* the chosen row: "| **A · escolhido** | fala | quadro 0 | texto na tela | tipo |" */
+  const g = /^\|\s*\**A\b[^|]*escolhido\**\s*\|([^|]*)\|([^|]*)\|([^|]*)\|([^|]*)\|/im.exec(md);
+  const clean = s => (s ?? "").trim() || null;
+  const hook =
+    g && clean(g[1]) && !/^a primeira frase$/i.test(g[1].trim())
+      ? { line: clean(g[1]), frame0: clean(g[2]), text: clean(g[3]), type: clean(g[4]) }
+      : null;
+  return { pillar: cell(md, "pilar"), goal: cell(md, "objetivo"), promise: cell(md, "promessa"), hook };
+}
+
+/* the video's cover, as the studio list shows it: the selected thumbnail or the first scene's still */
+function coverOf(dir) {
+  const selected = readJson(join(dir, "thumbnail", "thumbnail.json"))?.selected;
+  const id = readJson(join(dir, "scenes.json"))?.scenes?.[0]?.id;
+  for (const path of [selected ? "thumbnail/thumbnail.png" : null, id ? `motion/stills/${id}.png` : null]) {
+    if (!path) continue;
+    try {
+      return { path, size: 0, mtime: Math.round(statSync(join(dir, path)).mtimeMs) };
+    } catch {
+      /* doesn't exist */
+    }
+  }
+  return null;
+}
+const firstLine = dir => readJson(join(dir, "scenes.json"))?.scenes?.[0]?.lines?.[0]?.text ?? null;
+
+function median(values) {
+  const v = values.filter(x => typeof x === "number" && Number.isFinite(x)).sort((a, b) => a - b);
+  if (!v.length) return null;
+  const m = v.length >> 1;
+  return v.length % 2 ? v[m] : Math.round(((v[m - 1] + v[m]) / 2) * 10) / 10;
+}
+
+/* the channel medians on one reading (`current`) or one milestone ("24h", "72h"), with how many videos */
+function medians(videos, from) {
+  const snaps = videos
+    .map(v => (from === "current" ? v.current : v.snapshots.find(f => f.milestone === from)))
+    .filter(Boolean)
+    .map(withPerK);
+  return { n: snaps.length, ...Object.fromEntries(Object.keys(METRICS).map(k => [k, median(snaps.map(f => f[k]))])) };
+}
+
+function lastAnalysis() {
+  if (!existsSync(ANALYSES)) return null;
+  const name = readdirSync(ANALYSES)
+    .filter(n => /^\d{4}-\d{2}-\d{2}.*\.md$/.test(n))
+    .sort()
+    .at(-1);
+  if (!name) return null;
+  const path = join(ANALYSES, name);
+  return {
+    file: `channel/analyses/${name}`,
+    day: name.slice(0, 10),
+    at: new Date(statSync(path).mtimeMs).toISOString(),
+  };
+}
+
+/* the sum of the Reels hour by hour, over the last 30 days. Each Reel counts with its last reading
+   up to the end of that hour; before published, zero; between publishing and the first reading,
+   the line between zero and it (estimated); published before collection started, the first reading */
+const PROGRESSION_FIELDS = ["views", "comments", "saves"];
+/* one point per collection pass: the readings of one pass fall in the same minute */
+const MINUTE = 60_000;
+function progression(videos, accountHourly = []) {
+  const series = videos
+    .filter(v => !v.removed && v.hourly?.length)
+    .map(v => ({
+      pub: Date.parse(v.published_at),
+      hourly: [...v.hourly].sort((a, b) => Date.parse(a.at) - Date.parse(b.at)),
+    }));
+  const account = [...accountHourly]
+    .filter(h => h.followers != null)
+    .sort((a, b) => Date.parse(a.at) - Date.parse(b.at));
+  const minutes = [...series.flatMap(s => s.hourly.map(h => h.at)), ...account.map(h => h.at)].map(
+    at => Math.floor(Date.parse(at) / MINUTE) * MINUTE,
+  );
+  if (!minutes.length) return [];
+  const collectStart = Math.min(...minutes);
+  const end = Math.max(...minutes);
+  const instants = [...new Set(minutes)].filter(t => t >= end - 30 * 24 * H).sort((a, b) => a - b);
+  const points = [];
+  for (const t of instants) {
+    const point = { t, followers: account.filter(h => Date.parse(h.at) < t + MINUTE).at(-1)?.followers ?? null };
+    for (const c of PROGRESSION_FIELDS) point[c] = 0;
+    for (const s of series) {
+      if (s.pub >= t + MINUTE) continue;
+      const read = s.hourly.filter(h => Date.parse(h.at) < t + MINUTE).at(-1);
+      const first = s.hourly[0];
+      for (const c of PROGRESSION_FIELDS) {
+        let v = read?.[c];
+        if (v == null && s.pub < collectStart) v = first[c];
+        else if (v == null) {
+          const dt = Date.parse(first.at) - s.pub;
+          v = dt > 0 ? Math.round((first[c] ?? 0) * Math.min(1, (t + MINUTE - s.pub) / dt)) : first[c];
+        }
+        point[c] += v ?? 0;
+      }
+    }
+    points.push(point);
+  }
+  return points;
+}
+
+/* the 3 s skip range before OmniVideo, as the channel playbook writes it ("de 45% a 67%"; PT sentence) */
+function before() {
+  const md = readText(join(CHANNEL, "playbook.md")) ?? "";
+  const m = /Antes do OmniVideo[\s\S]{0,200}?pulo em 3\s*s[^\d]{0,20}(\d+(?:,\d+)?)%\s*a\s*(\d+(?:,\d+)?)%/i.exec(md);
+  return m ? { skip_3s_pct: [Number(m[1].replace(",", ".")), Number(m[2].replace(",", "."))] } : null;
+}
+
+export function context() {
+  const t = table();
+  const dirOf = slug => join(ROOT, "videos", slug);
+  const videos = t.videos.map(({ hourly = [], ...v }) => {
+    const dir = dirOf(v.slug);
+    const analysis = join(dir, "analysis.md");
+    return {
+      ...v,
+      n_hourly: hourly.length,
+      ...strategy(dir),
+      first_line: firstLine(dir),
+      cover: coverOf(dir),
+      analysis: existsSync(analysis) ? { at: new Date(statSync(analysis).mtimeMs).toISOString() } : null,
+      opening: existsSync(join(dir, "analysis", "opening.png")),
+    };
+  });
+  const withReading = videos.filter(v => v.current);
+  const prog = progression(t.videos, t.account_hourly);
+  const from = prog[0]?.t ?? Infinity;
+  return {
+    generated_at: new Date().toISOString(),
+    account: t.account,
+    medians: { current: medians(withReading, "current"), "24h": medians(videos, "24h"), "72h": medians(videos, "72h") },
+    progression: prog,
+    publications: videos
+      .filter(v => !v.removed && Date.parse(v.published_at) >= from)
+      .map(v => ({ t: Date.parse(v.published_at), slug: v.slug, title: v.title })),
+    before: before(),
+    videos,
+    agent: agentStatus(),
+    last_analysis: lastAnalysis(),
+    playbook: existsSync(join(CHANNEL, "playbook.md")),
+  };
+}
+
+/* the opening of the uploaded MP4, frame by frame: the Reel's visual hook */
+function frames(dir) {
+  const ig = readJson(join(dir, "publication.json"))?.instagram;
+  const mp4 = [ig?.mp4, readJson(join(dir, "export", "assembly.json"))?.mp4].find(p => p && existsSync(join(dir, p)));
+  if (!mp4) fail(`${basename(dir)} não tem o MP4 publicado nem o export`);
+  const outDir = join(dir, "analysis");
+  const tmp = join(outDir, ".frames");
+  mkdirSync(tmp, { recursive: true });
+  try {
+    FRAMES.forEach((t, i) => {
+      const r = spawnSync(
+        "ffmpeg",
+        [
+          "-v",
+          "error",
+          "-ss",
+          String(t),
+          "-i",
+          join(dir, mp4),
+          "-frames:v",
+          "1",
+          "-vf",
+          "scale=270:-2,pad=iw+8:ih+8:4:4:white",
+          "-y",
+          join(tmp, `q${i}.png`),
+        ],
+        { encoding: "utf8" },
+      );
+      if (r.status !== 0) fail(`ffmpeg no quadro ${t} s: ${(r.stderr || "").trim()}`);
+    });
+    const inputs = FRAMES.flatMap((_, i) => ["-i", join(tmp, `q${i}.png`)]);
+    const out = join(outDir, "opening.png");
+    const r = spawnSync(
+      "ffmpeg",
+      ["-v", "error", ...inputs, "-filter_complex", `hstack=inputs=${FRAMES.length}`, "-y", out],
+      { encoding: "utf8" },
+    );
+    if (r.status !== 0) fail(`ffmpeg ao juntar os quadros: ${(r.stderr || "").trim()}`);
+    console.log(`${out} · quadros em ${FRAMES.map(t => `${String(t).replace(".", ",")} s`).join(", ")} de ${mp4}`);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  const [cmd, target] = process.argv.slice(2);
+  if (cmd === "context") console.log(JSON.stringify(context(), null, 2));
+  else if (cmd === "frames" && target) {
+    const dir = resolve(target);
+    if (!existsSync(join(dir, "publication.json"))) fail(`${target} não tem publication.json`);
+    frames(dir);
+  } else fail("uso: analysis.mjs context · frames videos/<slug>");
+}