# av.film 库模块帮助文档

说明

av.film - 影音合成管线（音画总调度）：场景与元素（声明式）→ 自动音效 → 渲染 MP4 → 联系表/报告/lint > 这是智能影音编排引擎织影（autos.skills.codingFilm）的底层组件全局时钟：脚本里的数字就是成片秒数。元素的 at 是命中时刻（slam 是落地，其余是出现），音效对齐它。帧是时间的纯函数：任意帧可单独渲染（film.frame），结果可重复。

## av 成员列表 # ### av.film(width,height,opt) # 创建影片：opt: duration(秒),fps(默认 30),theme("midnight"|"punch"|"light"|{base="midnight";colors;bg;styles}),bpm,music("tech"|"upbeat"|"ambient"|"lofi"|clip|音频文件路径：mp3、m4a、wav，任意采样率),audio({musicMode="sectioned"|"continuous"|"none";sfxMode="auto"|"manual"|"none";autoAccents;musicEnergy;musicGain;musicFadeOut;duck;beatOffset}),seed,grain(false 关闭背景颗粒) [返回对象:avFilmObject](#avFilmObject) ## av.film 成员列表 # 影音合成管线（音画总调度）：场景与元素（声明式）→ 自动音效 → 渲染 MP4 → 联系表/报告/lint ### av.film.presets # 入场预设表：fade,rise,slide,pop,punch,slam,type,none；预设字段 fast={起,止,区域倍数} 声明相对命中时刻的有意急变窗口（闪烁检测跳过） ### av.film.themes # 主题表 ### av.film.transitions # 转场表：cut,fade,flash,wipe,push,zoom,glitch ## avFilmObject 成员列表 # ### avFilmObject.audio(src,opt) # 全片层声音（配音、旁白、录音），用法同 scene.audio ### avFilmObject.burst(kind,opt) # 全片层粒子 ### avFilmObject.chat(content,opt) # 全片层提示词框/对话卡，用法同 scene.chat ### avFilmObject.clip(path,opt) # 全片层外部画面，用法同 scene.clip ### avFilmObject.code(src,opt) # 全片层代码面板，用法同 scene.code ### avFilmObject.counter(from,to,opt) # 全片层数字滚动 ### avFilmObject.draw(fn,opt) # 全片层自绘，用法同 scene.draw ### avFilmObject.duration # 时长（秒） ### avFilmObject.fps # 帧率 ### avFilmObject.frame(t,path,opt) # 渲染单帧：指定 path 保存并返回路径，否则返回 gdip.bitmap ### avFilmObject.height # 高 ### avFilmObject.image(path,opt) # 全片层图片 ### avFilmObject.invalidate() # 直接修改元素/场景字段后使准备缓存失效，返回影片自身；追加元素或切换草稿会自动处理 ### avFilmObject.lint() # 检查，返回 {level;t;msg} 数组 ### avFilmObject.list(items,opt) # 全片层清单 ### avFilmObject.render(path,opt) # 渲染 MP4 并在旁边出联系表，返回报告（含闪烁检测结果 flicker 与 lint）； opt: draft(半分辨率),quality,sheet(false 不出联系表),flicker(false 不做闪烁检测) ### avFilmObject.report() # 文本时间线 ### avFilmObject.scene(start,end,opt) # 添加场景（全局时钟，秒）：opt: transition(cut|fade|flash|wipe|push|zoom|glitch),transitionSfx(false 关闭本场景转场音效),bg("dark"|"accent"|颜色|渐变表|图片路径) [返回对象:avFilmSceneObject](#avFilmSceneObject) ### avFilmObject.sfx(t,name,opt) # 手动音效（命中点对齐 t） ### avFilmObject.sheet(path,opt) # 联系表：opt: count(默认 16),times(时刻数组),draft ### avFilmObject.text(content,opt) # 全片层文字（跨场景、不随转场移动）；opt 同 scene.text ### avFilmObject.theme # 主题表 ### avFilmObject.width # 宽 ## avFilmSceneObject 成员列表 # ### avFilmSceneObject.audio(src,opt) # 外部声音（配音、旁白、录音、品牌音）：src 为音频文件路径（MP3/WAV/M4A 等）、av.audio.clip，或带 path 字段的表（可带 text：这段声音说的话；words：词时间 {{text;at;dur},...}，at 为相对开口的秒数）。声明时就解码：响度自动对齐、去掉首尾静音；返回表 .at 为开口、.done 为说完（成片秒）、.text 为台词：下一句写 at=v.done+0.3，画面文字写 s.text(v.text,{at=v.at})；v.word("代码"[,n]) 为说到这个词（第 n 次出现）时的成片秒，有 words 时精确到词，否则按声音里的停顿与字数估算。配音期间配乐自动压低。opt: at(默认场景起点),on(跟随某元素的 at),gain(dB),text,words(词时间，优先于来源表),name ### avFilmSceneObject.burst(kind,opt) # 粒子：kind 为 "sparkle"|"confetti"；opt: on(目标元素),at,x,y, radius(自定星光半径，不避让；默认跟随目标大小并避让邻近静态元素),behind(false 保留前景星光；默认在同层目标后面) ### avFilmSceneObject.chat(content,opt) # 字符串 = 提示词框（打字、光标、发送键）；{{说话人;消息},...} = 对话卡。返回表 .done。 opt: at,speed(字/秒，默认 12),color(其余说话人颜色),size,bold,font,卡片词,x,y,pos,enter,sfx ### avFilmSceneObject.clip(path,opt) # 外部画面（只接入不采集，静音）：path 为 PNG 序列 "前缀-*.png" 或视频文件； opt: at,from(素材起点秒，负数先定格首帧),speed(默认 1，0 定格取帧),width,height,卡片词,zoom,x,y,pos,enter,out,opacity,scale ### avFilmSceneObject.code(src,opt) # 代码面板：src 为多行字符串或行数组；自动着色与打字；返回表 .done 为打完的成片秒。 opt: at,speed(字符/秒，默认 50，0 不打字),focus(打完后高亮的行号或数组),lineNumbers(true 或每行号码数组), edits({{本地秒;"旧片段";"新片段"},...}，片段须唯一),size,bold,font,卡片词(width,height,title,caption,bg,border,radius,shadow),x,y,pos,enter,sfx ### avFilmSceneObject.counter(from,to,opt) # 数字滚动：opt: at,dur,format(printf),style(默认 hero；界面小号数字用 body),size,bold,font,x,y,align,color ### avFilmSceneObject.draw(fn,opt) # 自绘 fn(g,t,e)：g 为设计坐标，按不透明画（淡入淡出、入场退场由引擎作用在整个元素上）；t 为元素本地秒。 opt 给 width,height 为方框元素（g 原点在框左上角，参与自动排版，默认 fade），否则整屏画布；方框可加卡片词 title/caption/bg/border/radius/shadow（有 title 时 g 与 e.width/e.height 是内容区）； opt 还可有 at,out,enter,opacity,scale,rotate,x,y(方框中心),pos,name,sfx。 e: brush(色,不透明度)/pen(色,宽,不透明度)（自动释放）、text(字,x,y,样式名或选项)、 image(路径,x,y,宽,高,{radius;opacity})、glow(x,y,半径,色)、progress(a,b,缓动)、color(色,不透明度)、 box(元素[,code 片段]) 取声明元素在当前坐标系里的矩形；t,time,width,height,theme,seed ### avFilmSceneObject.end # 结束秒数 ### avFilmSceneObject.image(path,opt) # 图片：opt: at,width,height,radius(圆角),shadow(false 关闭投影),x,y(卡片中心),scale,rotate,enter（大图默认 Ken Burns）；卡片词：title(卡内窗口标题栏),caption(卡外说明),bg,border(true 或颜色),zoom(数值或 {{本地秒;倍数;中心x;中心y[;缓动]}}) ### avFilmSceneObject.list(items,opt) # 清单：opt: at,stagger(秒或每项偏移数组),icon(图标名),style,size,bold,font,color,enter,x,y,align, row(横排),step(依次点亮+箭头),border/bg(每项一颗圆角小卡：true 或颜色),radius ### avFilmSceneObject.start # 开始秒数 ### avFilmSceneObject.text(content,opt) # 文字：content 可为字符串（**强调**、`'\n'` 分行）或 function(t)； opt: at(命中时刻),out,style(hero|title|subtitle|body|caption),size,bold,font(内联，盖过样式；size 为画面像素), enter(fade|rise|slide|pop|punch|slam|type|none),pos(top|bottom|center|left|right),x,y,align,opacity,rotate,scale, split(char|word|line),stagger,color,sfx(false|音效名|{名字;参数}|{{相对 at 的秒数,名字,参数...},...})