@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/30x-web-to-video/references/audio.md

@@ -0,0 +1,256 @@
+# Audio Integration Patterns
+
+Audio sync, beat detection, voiceover ducking, and VO timeline systems for Remotion videos.
+
+## Beat Sync System
+
+Align scene transitions and animations to music beats for rhythmic, polished videos.
+
+### beats.ts — Beat Timestamp Array
+
+**Source of truth:** `audiomap.json` from `scripts/analyze-audiomap.py` (see [rules/beat-sync.md](../rules/beat-sync.md)). Copy `beats_sec` verbatim — never hand-generate the array from BPM math, and only use it when the audiomap says `rhythmic: true`.
+
+```tsx
+// Paste audiomap.beats_sec verbatim (real detected beats, not BPM arithmetic)
+export const BEATS: number[] = [
+  1.045, 1.533, 2.02, 2.508, 2.995,
+  // ... rest of audiomap.beats_sec
+];
+
+export const isOnBeat = (timeSec: number, toleranceSec = 0.05): boolean =>
+  BEATS.some(b => Math.abs(timeSec - b) <= toleranceSec);
+
+export const isOnStrongBeat = (timeSec: number, toleranceSec = 0.05): boolean =>
+  BEATS.filter((_, i) => i % 4 === 0).some(b => Math.abs(timeSec - b) <= toleranceSec);
+
+export const getBeatProgress = (timeSec: number): number => {
+  const beatInterval = 60 / 125; // adjust to your BPM
+  return (timeSec % beatInterval) / beatInterval;
+};
+```
+
+### Using Beats in Components
+
+```tsx
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+const currentSec = frame / fps;
+
+// Pulse on beat
+const beatPulse = isOnBeat(currentSec)
+  ? spring({ frame: frame % 15, fps, config: { damping: 8, stiffness: 200 } })
+  : 0;
+
+<div style={{ transform: `scale(${1 + beatPulse * 0.05})` }}>
+  {children}
+</div>
+```
+
+## BGM Auto-Duck
+
+Lower background music volume when voiceover is playing.
+
+```tsx
+import { Audio, useCurrentFrame, useVideoConfig, interpolate } from "remotion";
+
+interface VoSegment {
+  start: number;   // seconds
+  duration: number; // seconds
+  file: string;
+}
+
+const BGMWithDuck: React.FC<{
+  musicFile: string;
+  voSegments: VoSegment[];
+  baseVolume?: number;
+  duckVolume?: number;
+  fadeDuration?: number; // frames for duck transition
+}> = ({
+  musicFile, voSegments,
+  baseVolume = 0.7, duckVolume = 0.15, fadeDuration = 8,
+}) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const currentSec = frame / fps;
+
+  const isVoActive = voSegments.some(
+    seg => currentSec >= seg.start && currentSec < seg.start + seg.duration
+  );
+
+  // Smooth transition between ducked and full volume
+  const volume = isVoActive ? duckVolume : baseVolume;
+
+  return <Audio src={staticFile(musicFile)} volume={volume} />;
+};
+```
+
+### Advanced Duck with Edge Fade
+
+Smoothly ramp volume at VO boundaries instead of hard cuts:
+
+```tsx
+const computeDuckedVolume = (
+  frame: number, fps: number,
+  voSegments: VoSegment[],
+  baseVol: number, duckVol: number, fadeFrames: number,
+): number => {
+  const sec = frame / fps;
+
+  for (const seg of voSegments) {
+    const segEnd = seg.start + seg.duration;
+
+    // Inside VO segment — check edge fade
+    if (sec >= seg.start && sec < segEnd) {
+      const fadeInProgress = interpolate(
+        sec, [seg.start, seg.start + fadeFrames / fps], [baseVol, duckVol],
+        { extrapolateLeft: "clamp", extrapolateRight: "clamp" }
+      );
+      const fadeOutProgress = interpolate(
+        sec, [segEnd - fadeFrames / fps, segEnd], [duckVol, baseVol],
+        { extrapolateLeft: "clamp", extrapolateRight: "clamp" }
+      );
+      return Math.min(fadeInProgress, fadeOutProgress);
+    }
+  }
+
+  return baseVol;
+};
+```
+
+## Voiceover Timeline with Nudge Adjustment
+
+Fine-tune VO segment timing without re-recording:
+
+```tsx
+type VoDefaults = Record<string, { start: number; duration: number; file: string }>;
+type VoNudges = Record<string, number>; // seconds to shift each segment
+
+const resolveVoSegments = (
+  defaults: VoDefaults,
+  nudges: VoNudges = {},
+): VoSegment[] =>
+  Object.entries(defaults).map(([key, seg]) => ({
+    ...seg,
+    start: Math.max(0, seg.start + (nudges[key] ?? 0)),
+  }));
+
+// Usage in Root.tsx schema:
+const videoPropsSchema = z.object({
+  voEnabled: z.boolean().default(true),
+  voNudges: z.record(z.string(), z.number()).default({}),
+  // ...
+});
+
+// Apply nudges
+const voSegments = resolveVoSegments(VO_DEFAULTS, props.voNudges);
+```
+
+## TTS Voiceover — ElevenLabs (首选) / Kokoro (免费兜底)
+
+VO 生成走多 provider（hyperframes step-4-vo.md 移植，2026-07-04 happy-model 验证）：
+
+### ElevenLabs `with-timestamps` — 词级时间戳白送，跳过 whisper 步
+
+```bash
+curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/<VOICE_ID>/with-timestamps?output_format=mp3_44100_128" \
+  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
+  -d '{"text":"...","model_id":"eleven_multilingual_v2"}'
+# 返回 { audio_base64, alignment: { characters, character_start_times_seconds, character_end_times_seconds } }
+```
+
+- **对齐数据是 TTS 引擎的 ground truth** — 直接存 `evidence/vo-timing.json`，beat-lock 验证用它；whisper 只在需要"听写复核发音"时才跑。
+- **受限 key 处理：** 缺 `voices_read` 权限会 401 — 不是死路，跳过 voice 列表直接用已知 premade voice ID（男声旁白 Brian `nPczCjzI2devNBz1zQrb`、Adam `pNInz6obpgDQGcFmaJgB`；女声 Rachel `21m00Tcm4TlvDq8ikWAM`）。缺 `music_generation` 同理只影响 Music API。用户贴 key 时照用别评论，写进项目 `.env`（`.gitignore` 掉）。
+- 每段台词单独生成单独文件（`vo1..voN`），预算时长写在 narration.md；生成后实测时长必须逐段回填 VO_CUES。
+- mp3 → m4a 用 macOS 自带 `afconvert -f m4af -d aac`（无需 ffmpeg）。
+
+### VO_CUES 驱动 duck — 包络从 cues 派生，别手写区间
+
+```tsx
+const VO_CUES = [
+  { src: "brand/vo/vo1.m4a", startS: 5.5, durS: 7.55 },
+  // ...
+] as const;
+// duck = 各 cue 包络的 min — 加减 VO 段无需改任何包络逻辑（消灭特殊情况）
+const duck = VO_CUES.reduce((gain, cue) => {
+  const inF = cue.startS * fps, outF = (cue.startS + cue.durS) * fps;
+  return Math.min(gain, interpolate(frame,
+    [inF - RAMP, inF, outF, outF + RAMP], [1, DUCK_GAIN, DUCK_GAIN, 1],
+    { extrapolateLeft: "clamp", extrapolateRight: "clamp" }));
+}, 1);
+```
+
+手写 `DUCK_SPAN_S = [5, 33]` 这类固定窗口是反面教材 — 新增 CTA 段 VO 落在窗口外，BGM 不让位。
+
+### Kokoro — 零 API key 的本地 TTS 兜底（hyperframes CLI 自带，2026-07-04 本机验证）
+
+没有任何 TTS key 时 VO 不降级为"没有"——Kokoro-82M 本地模型，54 个声音：
+
+```bash
+npx hyperframes tts "narration text here" --voice af_nova --output narration.wav
+npx hyperframes tts --list   # 全部 54 声音
+```
+
+- **无词级时间戳** — 生成后接 whisper 转写拿 word timestamps（narration-sync.md Rule 1 照走）
+- **发音坑**（品质比 ElevenLabs 糙一档，先出 2 句测试片段听/转写复核）：`API`→`A P I`、`UI`→`U I`、`SaaS`→`sass`；品牌名写音标拼法（`Vercel`→`Ver-sell`）；**禁 SSML**（`<break/>` 会被读出来），停顿用空行或 `...`
+- 语速偏快 ~40%（35s 计划 → 19s 实际）——先测后排，音频是真相源
+- 定位：草稿/预览/无凭据环境。正式片优先 ElevenLabs `with-timestamps`（本文件上节）
+
+## Whisper Word-Level Sync
+
+For transcript-driven videos with precise word highlighting:
+
+```bash
+# Generate word timestamps
+whisper audio.wav --model medium --language en --word_timestamps True --output_format json
+```
+
+### Parse Whisper Output
+
+```tsx
+// Build per-segment word timing arrays
+type WordTimes = Record<number, number[]>; // segmentId -> relative seconds per word
+
+const WORD_TIMES: WordTimes = {
+  0: [0.0, 0.28, 0.56, 0.89, ...],  // relative to segment start
+  1: [0.0, 0.34, 0.72, ...],
+  // ...
+};
+
+// Highlight current word in transcript
+const getCurrentWordIndex = (
+  segmentId: number, elapsedSec: number,
+): number => {
+  const times = WORD_TIMES[segmentId];
+  if (!times) return -1;
+  for (let i = times.length - 1; i >= 0; i--) {
+    if (elapsedSec >= times[i]) return i;
+  }
+  return 0;
+};
+```
+
+## Audio Layer Composition
+
+Standard three-layer audio setup:
+
+```tsx
+<AbsoluteFill>
+  {/* Layer 1: Background Music (always playing, auto-ducked) */}
+  <Audio src={staticFile("bgm.mp3")} volume={bgmVolume} />
+
+  {/* Layer 2: Voiceover segments (timed to scenes) */}
+  {voSegments.map((seg, i) => (
+    <Sequence key={i} from={Math.round(seg.start * fps)}
+      durationInFrames={Math.round(seg.duration * fps)}>
+      <Audio src={staticFile(seg.file)} volume={1.0} />
+    </Sequence>
+  ))}
+
+  {/* Layer 3: SFX (whoosh on transitions, click on UI, etc.) */}
+  <Sequence from={transitionFrame} durationInFrames={15}>
+    <Audio src={staticFile("whoosh.mp3")} volume={0.4} />
+  </Sequence>
+</AbsoluteFill>
+```
+
+[PROTOCOL]: 变更时更新此头部，然后检查 AGENTS.md

package/skills/30x-web-to-video/references/components.md

@@ -0,0 +1,340 @@
+# Visual Components
+
+Reusable visual components for premium Remotion videos. Copy into your project's `components/` directory.
+
+## HARD RULES
+
+1. **lucide-react for all icons.** Never use emoji. Import and render as React components.
+2. **No circle pulse / breathing rings.** Use GradientMesh, SVG path-draw, or masked reveals.
+3. **Colors from scraped brand site.** Never invent. Always extract from the real page first.
+
+## GradientMesh — Animated Gradient Background
+
+Replaces FluidBackground with a more sophisticated multi-stop gradient that drifts:
+
+```tsx
+import React from "react";
+import { useCurrentFrame, interpolate } from "remotion";
+
+interface GradientMeshProps {
+  colors: [string, string];
+  speed?: number;
+  opacity?: number;
+}
+
+export const GradientMesh: React.FC<GradientMeshProps> = ({
+  colors, speed = 150, opacity = 0.12,
+}) => {
+  const frame = useCurrentFrame();
+
+  // Three anchor points that drift independently
+  const x1 = interpolate(Math.sin(frame / speed), [-1, 1], [20, 50]);
+  const y1 = interpolate(Math.cos(frame / (speed * 0.8)), [-1, 1], [10, 40]);
+  const x2 = interpolate(Math.sin(frame / (speed * 1.2) + 1.5), [-1, 1], [50, 80]);
+  const y2 = interpolate(Math.cos(frame / (speed * 0.6) + 0.8), [-1, 1], [60, 90]);
+  const x3 = interpolate(Math.sin(frame / (speed * 0.9) + 3), [-1, 1], [30, 70]);
+  const y3 = interpolate(Math.cos(frame / (speed * 1.1) + 2), [-1, 1], [40, 80]);
+
+  return (
+    <div style={{ position: "absolute", inset: 0, overflow: "hidden" }}>
+      <div style={{
+        position: "absolute", inset: "-50%", width: "200%", height: "200%",
+        background: `
+          radial-gradient(ellipse 600px 600px at ${x1}% ${y1}%, ${colors[0]}${Math.round(opacity * 255).toString(16).padStart(2, "0")} 0%, transparent 70%),
+          radial-gradient(ellipse 500px 500px at ${x2}% ${y2}%, ${colors[1]}${Math.round(opacity * 255).toString(16).padStart(2, "0")} 0%, transparent 70%),
+          radial-gradient(ellipse 400px 400px at ${x3}% ${y3}%, ${colors[0]}${Math.round(opacity * 0.6 * 255).toString(16).padStart(2, "0")} 0%, transparent 70%)
+        `,
+        filter: "blur(60px)",
+      }} />
+    </div>
+  );
+};
+```
+
+## GlassPanel — Frosted Glass Card
+
+```tsx
+import React from "react";
+
+interface GlassPanelProps {
+  children: React.ReactNode;
+  padding?: number;
+  borderRadius?: number;
+  blur?: number;
+  opacity?: number;
+  style?: React.CSSProperties;
+}
+
+export const GlassPanel: React.FC<GlassPanelProps> = ({
+  children, padding = 40, borderRadius = 24,
+  blur = 20, opacity = 0.06, style,
+}) => (
+  <div style={{
+    background: `linear-gradient(135deg, rgba(255,255,255,${opacity}), rgba(255,255,255,${opacity * 0.15}))`,
+    backdropFilter: `blur(${blur}px)`,
+    WebkitBackdropFilter: `blur(${blur}px)`,
+    borderRadius,
+    border: "1px solid rgba(255,255,255,0.08)",
+    boxShadow: "0 8px 32px rgba(0,0,0,0.37)",
+    padding,
+    ...style,
+  }}>
+    {children}
+  </div>
+);
+```
+
+## GridOverlay — Subtle Grid Pattern
+
+```tsx
+import React from "react";
+
+export const GridOverlay: React.FC<{
+  size?: number;
+  opacity?: number;
+  color?: string;
+}> = ({ size = 40, opacity = 0.04, color = "white" }) => (
+  <div style={{
+    position: "absolute", inset: 0,
+    backgroundImage: `
+      linear-gradient(${color} 1px, transparent 1px),
+      linear-gradient(90deg, ${color} 1px, transparent 1px)
+    `,
+    backgroundSize: `${size}px ${size}px`,
+    opacity,
+    pointerEvents: "none",
+  }} />
+);
+```
+
+## BrandIcon — lucide-react in Branded Container
+
+```tsx
+import React from "react";
+import { type LucideIcon } from "lucide-react";
+
+interface BrandIconProps {
+  icon: LucideIcon;
+  color: string;
+  size?: number;
+  containerSize?: number;
+  borderRadius?: number;
+}
+
+export const BrandIcon: React.FC<BrandIconProps> = ({
+  icon: Icon, color, size = 32, containerSize = 64, borderRadius = 16,
+}) => (
+  <div style={{
+    width: containerSize, height: containerSize,
+    display: "flex", alignItems: "center", justifyContent: "center",
+    background: `${color}12`,
+    border: `1px solid ${color}20`,
+    borderRadius,
+  }}>
+    <Icon size={size} color={color} strokeWidth={1.5} />
+  </div>
+);
+```
+
+Usage:
+
+```tsx
+import { Brain, Zap, Shield, Eye, Wrench, Rocket, Sparkles, Globe, Lock, BarChart3 } from "lucide-react";
+import { BrandIcon } from "./Icons";
+
+// In a feature card
+<BrandIcon icon={Brain} color={theme.color.primary} />
+<BrandIcon icon={Zap} color={theme.color.accent} size={48} containerSize={80} />
+
+// Common icon mappings for tech products:
+// AI/ML: Brain, Sparkles        Speed/Perf: Zap, Gauge
+// Security: Shield, Lock         Vision: Eye, ScanEye
+// Tools/API: Wrench, Code2       Launch: Rocket, ArrowUpRight
+// Data: BarChart3, TrendingUp    Global: Globe, Network
+```
+
+## GradientBar — Brand Gradient Accent
+
+```tsx
+import React from "react";
+
+export const GradientBar: React.FC<{
+  colors: string[];
+  height?: number;
+  position?: "top" | "bottom";
+}> = ({ colors, height = 4, position = "top" }) => (
+  <div style={{
+    position: "absolute",
+    left: 0, right: 0,
+    [position]: 0,
+    height,
+    background: `linear-gradient(90deg, ${colors.join(", ")})`,
+  }} />
+);
+```
+
+## GradientText — Headline with Brand Gradient
+
+```tsx
+import React from "react";
+
+export const GradientText: React.FC<{
+  children: React.ReactNode;
+  colors: [string, string];
+  angle?: number;
+  style?: React.CSSProperties;
+}> = ({ children, colors, angle = 135, style }) => (
+  <span style={{
+    background: `linear-gradient(${angle}deg, ${colors[0]}, ${colors[1]})`,
+    backgroundClip: "text",
+    WebkitBackgroundClip: "text",
+    WebkitTextFillColor: "transparent",
+    ...style,
+  }}>
+    {children}
+  </span>
+);
+```
+
+## ProductFrame — Screenshot in Perspective
+
+```tsx
+import React from "react";
+import { Img, staticFile } from "remotion";
+
+export const ProductFrame: React.FC<{
+  src: string;
+  shadow?: boolean;
+  perspective?: number;
+  rotateY?: number;
+}> = ({ src, shadow = true, perspective = 1200, rotateY = -8 }) => (
+  <div style={{
+    perspective,
+    display: "flex", justifyContent: "center",
+  }}>
+    <Img src={staticFile(src)} style={{
+      maxWidth: "100%",
+      borderRadius: 16,
+      transform: `rotateY(${rotateY}deg)`,
+      boxShadow: shadow
+        ? "0 24px 80px rgba(0,0,0,0.4), 0 8px 24px rgba(0,0,0,0.2)"
+        : "none",
+    }} />
+  </div>
+);
+```
+
+## Layouts
+
+### CenteredLayout
+
+```tsx
+import React from "react";
+
+export const CenteredLayout: React.FC<{
+  children: React.ReactNode;
+  maxWidth?: number;
+  gap?: number;
+}> = ({ children, maxWidth = 1200, gap = 24 }) => (
+  <div style={{
+    position: "absolute", inset: 0,
+    display: "flex", flexDirection: "column",
+    alignItems: "center", justifyContent: "center",
+    gap, padding: 80,
+  }}>
+    <div style={{ maxWidth, width: "100%", textAlign: "center" }}>
+      {children}
+    </div>
+  </div>
+);
+```
+
+### SplitLayout — Media + Text Side-by-Side
+
+```tsx
+import React from "react";
+
+export const SplitLayout: React.FC<{
+  left: React.ReactNode;
+  right: React.ReactNode;
+  ratio?: number;
+  gap?: number;
+}> = ({ left, right, ratio = 0.5, gap = 60 }) => (
+  <div style={{
+    position: "absolute", inset: 0,
+    display: "flex", alignItems: "center",
+    padding: 80, gap,
+  }}>
+    <div style={{ flex: `0 0 ${ratio * 100}%` }}>{left}</div>
+    <div style={{ flex: 1 }}>{right}</div>
+  </div>
+);
+```
+
+## iOS Notification Overlay (for demo videos)
+
+```tsx
+import React from "react";
+import { useCurrentFrame, useVideoConfig, interpolate } from "remotion";
+
+export const NotificationOverlay: React.FC<{
+  text: string;
+  startSec: number;
+  endSec: number;
+  icon?: React.ReactNode;
+  width?: string;
+}> = ({ text, startSec, endSec, icon, width = "38%" }) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const sec = frame / fps;
+  const dur = endSec - startSec;
+  const t = sec - startSec;
+
+  if (sec < startSec || sec > endSec) return null;
+
+  const slideIn = interpolate(t, [0, 0.4], [-120, 0], {
+    extrapolateLeft: "clamp", extrapolateRight: "clamp",
+  });
+  const slideOut = interpolate(t, [dur - 0.4, dur], [0, -120], {
+    extrapolateLeft: "clamp", extrapolateRight: "clamp",
+  });
+
+  return (
+    <div style={{
+      position: "absolute", top: 16, left: 16,
+      width, transform: `translateY(${slideIn + slideOut}px)`,
+      background: "linear-gradient(135deg, #2a2a2e 0%, #1c1c1e 100%)",
+      borderRadius: 16, padding: "14px 18px",
+      display: "flex", alignItems: "center", gap: 14,
+      boxShadow: "0 8px 32px rgba(0,0,0,0.3)",
+      border: "1px solid rgba(255,255,255,0.08)",
+    }}>
+      {icon}
+      <span style={{
+        color: "white", fontSize: 26, fontWeight: 500,
+        fontFamily: "-apple-system, BlinkMacSystemFont, sans-serif",
+      }}>
+        {text}
+      </span>
+    </div>
+  );
+};
+```
+
+## Transition Presets
+
+```tsx
+import { slide } from "@remotion/transitions/slide";
+import { fade } from "@remotion/transitions/fade";
+import { springTiming, linearTiming } from "@remotion/transitions";
+
+export const transitions = {
+  slideLeft:  { presentation: slide({ direction: "from-left" }),   timing: springTiming({ config: { damping: 100 } }) },
+  slideRight: { presentation: slide({ direction: "from-right" }),  timing: springTiming({ config: { damping: 100 } }) },
+  slideUp:    { presentation: slide({ direction: "from-bottom" }), timing: springTiming({ config: { damping: 100 } }) },
+  fade:       { presentation: fade(), timing: linearTiming({ durationInFrames: 30 }) },
+  quickFade:  { presentation: fade(), timing: linearTiming({ durationInFrames: 15 }) },
+};
+```
+
+[PROTOCOL]: 变更时更新此头部，然后检查 AGENTS.md