# 织影 codingFilm：AI 智能影音编排引擎 ## 定位 织影 = 用代码编排整部短片（Coding Film）：画面是时间的纯函数，音效跟着画面命中点自动生成，配乐按显式声音策略现场合成；先做声音预检（WAV、JSON 报告与三段试听），再输出 MP4 和联系表。自动检查包括 lint、源帧单帧闪烁检测、混音响度/真峰值；**不等于对文案、审美或最终压缩文件的全面验收**。 基础链路随 aardio 提供：`av.film`（编排）+ `av.video`（动效）+ `av.audio`（声音）+ `sys.mediaFoundation`（编码），不必另装 Node/FFmpeg。AI 配图需要已配置的图像接口、网络和额度；Blender 等是可选工具，不把所有能力统称“零安装、全免费”。 - 主战场：信息类短片——文字动效、卖点清单、数字、截图卡片、提示词与对话、代码特写、外部画面（序列帧/MP4）、logo，加上每支片自己的招牌自绘。本机样片 20 秒 1080p 约 20~25 秒出片，具体随硬件和画面复杂度变化。 - 分工：内容型画面用声明元素（一行一个），这支片独有的招牌镜头用自绘（原生 gdip，没有上限）；策划时就定下招牌镜头。 - 配音是可选项，不是这类片子的重点：需要“有人说话”（旁白、一问一答、方言对白）时，`autos.skills.codingFilm.tts` 按角色表选音色（男声女声、播音腔或活泼、粤语、陕西话、东北话……），逐句合成并缓存，用 `s.audio` 放进片子。音画字一体：每句配音的字都长在画面里（标题、对话卡、要点），随开口出现；不做传统视频呆板的字幕条，Coding Film 的文字应当都是有生命的（不仅位置灵活，也可以动起来，能与视频音频融为一体）。影片只认音频文件：别的 TTS 技能包、真人录音、用户给的 mp3 同样能用。见 compose.md「配音」。 - 做不到的直说并给替代：实拍/写实画面（视频生成模型）、口型、视频原声。彩色 emoji、3D、复杂排版：先用 web.view 或 Blender 技能包渲染成图片或序列帧，再用 image/clip 放进来。背景、氛围图、概念插画可用 `generate_image` 生成或单图编辑（每次一张源图，见 compose.md「AI 配图」）。 ## 两个阶段，分开做 1. **策划**（读 `knowledge/planning.md`）：和用户对齐目的、观众、规格、风格、文案，写成项目的 HANDOFF.md（简报 + 分镜 + 素材 + 决定）。**用户确认分镜之前不写影片脚本代码。** 2. **编排影片**（读 `knowledge/compose.md` 和 av.film 指南）：按 HANDOFF 写 film.aardio → 静帧/布局自检 → `audioPreview` 声音预检与试听 → 渲染 MP4 → 自检 → 交付 → 按反馈改版。 - 判断阶段：没有项目，或 HANDOFF 的分镜还没经用户确认 → 策划；HANDOFF 阶段为「策划已确认」或已有版本 → 编排。 - 策划确认后：HANDOFF 阶段改为「策划已确认」，主记忆只写一行索引（项目名、HANDOFF 路径、阶段），然后提示用户：**清除当前对话，在新会话说「按 编排影片」**。理由：策划的来回讨论很长，编排要把上下文留给脚本代码、渲染报告和改版；结论都在 HANDOFF 里。用户明确要在本会话继续（如很短的片子）就直接编排。 - 用户用 `/grill-me` 开始时：对话方式听 grill-me 的；本技能提供要澄清的事项和分镜写法（planning.md），成果写进同一份 HANDOFF。 ## 项目目录（每个视频一个） ``` /films/<项目名>/ 默认建在 Autos 工作区；用户指定了目录就用用户的 ├─ HANDOFF.md 必需。唯一的项目状态来源：状态、简报、分镜、素材、决定、待定、版本记录 ├─ film.aardio 编排阶段创建。影片脚本代码（单文件，可直接运行）；另一个版本（如竖屏）另起 film-<变体>.aardio ├─ res/ 素材：logo、截图、照片、AI 配图（aardio 代码里写 "/res/logo.png"） └─ artifacts/ 渲染产物：<名>.mp4、.sheet.png（联系表）、.flicker.png；声音预检放在 `artifacts/audio-preview/`（soundtrack.wav、audio-report.json、preview-*.wav）；改版前把上一版移到 artifacts/v1/、v2/… ``` ```aardio import autos.skills.codingFilm; var cf = autos.skills.codingFilm; //只给名字则建在 /films/ 下，也可给完整路径；已存在的 HANDOFF.md 不覆盖 var p = cf.createProject("产品宣传片"); //{dir;name;handoff;res;artifacts;script;created} var list = cf.listProjects(); //{name;dir;stage} 数组，主记忆里没有索引时找项目用 ``` 内联代码（execute_code 默认 AppBase = 工作区）里 `/films/` 就是工作区下的 films 目录。 ## HANDOFF.md 规则 - 新会话先读它，它说了算；主记忆只存索引，不复制方案。 - 策划写：状态、简报、分镜、素材、决定、待定。编排写：状态、版本记录（每版的渲染指标、用户反馈原话、改动）。改了分镜就同步改表；被推翻的决定直接改，不留两套。 - 保持短：分镜一行一个场景，技术细节写在代码注释里。区分「用户原话」与「AI 自查/视觉模型建议」，不要混记来源。用户已授权审美细节时自行决策，只问真正影响方向或事实的问题。 - 织影本身不好用（API 不够、文档没写清、渲染出错）时，在「织影改进建议」记一行现象和绕过办法——这是给织影开发者的反馈。 ## 运行脚本代码 - `execute_code(code="<项目目录>/film.aardio")`：AppBase 自动是项目目录，代码里的 `/res/…`、`/artifacts/…` 都相对项目目录，不要再传 appBaseDirectory。 - 渲染是同步的，直接跑，不必另开线程。 ## P1：声音预检（先听，再渲染） 编排脚本确定画面和声音策略后，先调用： ```aardio import autos.skills.codingFilm; var preview = autos.skills.codingFilm.audioPreview(film,{dir="/artifacts/audio-preview";segmentSeconds=5;bits=16}); if(!preview.audioOk) error("音频预检失败，请先看 " ++ preview.reportPath,2); ``` 它不创建 MP4，只输出： - `soundtrack.wav`：编码前的整段最终 PCM 混音； - `audio-report.json`：策略、来源、总线 duck、每小节响度、事件局部响度、lint 与时间线； - `preview-01-intro.wav`、`preview-02-middle.wav`、`preview-03-outro.wav`：默认从片头、片中、片尾截取的三段试听。 先试听三段再整片渲染。`audioOk` 只表示声音能构建；`ok` 还会把视觉 lint error 算进去。声音问题先冻结画面时间线，不通过删 `bpm`、修改全局转场表或把音效偷偷预混进 music 绕过检查。 ## 知识路由 | 需要 | 读 | |---|---| | 策划：要定的事（含招牌镜头）、分镜写法、镜头菜单、节奏与文案、结构模板 | `knowledge/planning.md` | | 编排：分工、脚本代码骨架与约定、检查循环、自检、交付与改版、自绘菜单与“从轮子学手艺”、常见坑 | `knowledge/compose.md` | | av.film 完整 API：场景、元素、入场预设、转场、主题、配乐、lint、闪烁检测 | `~/docs/library/av/film/index.md`（编排前必读） | | 自绘用的缓动、关键帧、弹簧、种子噪声、颜色工具 | `~/docs/library/av/video/index.md` | | 手动音效名与参数、配乐风格 | `~/docs/library/av/audio/index.md` | | 音频预检与三段试听 | 本节 P1；实现为 `autos.skills.codingFilm.audioPreview` | | 配音：角色表、中文音色表、音画字一体的做法、换引擎 | `knowledge/compose.md`「配音」；Edge 音色与参数 `~/docs/library/web/edgeTextToSpeech/index.md` | knowledge 文件在 `~/lib/autos/skills/codingFilm/.res/knowledge/`。