yingwang/inktofilm

inktofilm 是做什么的？

将一个自然语言提示作为完整的起点。用户无需编写代码、运行命令、理解模型或准备剧本。

用户体验

• 从用户的想法开始。当重要的创意方向缺失时，做出强默认或提供一个简洁的概念供批准；仅询问那些会实质性改变电影的问题。
• 代表用户完成设置、规划、生成、评估、重试和编辑工作。除非用户询问，否则不展示内部命令、提供商负载或实现细节。
• 当持续时间和格式未指定时，默认为一个完整的 30 秒、16:9 的电影短片或预告片。对于长片或系列，首先创建一个经批准的概念验证短片，然后按照章节或剧集继续，并共享角色和世界设定档案。

私有设置和付费生成

如果已有 InkToFilm 仓库，则使用它。否则，从 https://github.com/yingwang/inktofilm 准备一个项目本地仓库和项目本地环境；不要修改无关的系统配置。在生产前验证 FFmpeg、FFprobe 和 fal 客户端；inktofilm doctor 会报告缺少的内容。

1. 在进程环境中查找 FAL_KEY，然后在项目本地的 .env 文件中查找。CLI 只读取环境变量，因此将文件加载到运行它的 shell 中，例如使用 set -a; . ./.env; set +a，并且永远不要打印该值。
2. 如果不存在，向用户请求一次他们的 fal API 密钥。当有已登录的浏览器可用时，提供创建和复制 API 范围密钥的选项，并明确获得批准，而不是让用户在聊天中暴露密钥。
3. 切勿回显、记录、总结、放入提示或提交密钥。仅将其存储在忽略的本地 .env 文件中，模式为 0600，并在任何提交或推送前验证 Git 会忽略该文件。
4. 阅读当前提供商定价，估计生成的秒数和重试配额，说明硬性支出上限，并在首次付费请求之前立即获得确认。在批准的限额之前停止。fal 按生成的每秒对 MiniMax H3 Max 计费，按静止图像对 nano-banana 计费，因此一个包含静止图像和几次重试的五镜头 30 秒电影通常花费几美元；请查看模型页面了解当前费率，而不是假设。

制作电影

使用运行此技能的 agent 进行创意和评判工作，并以 fal MiniMax H3 Max 作为默认视频生成器，同时尊重用户明确选择的任何模型。

• 在 Claude Code 中，您是规划者和评判者。自己编写剧本、计划以及测试套件，并按照以下阶段工作，以便在视频信用花费之前检查每个图像。要评判一个镜头，使用 inktofilm frames 采样评估器使用的相同均匀间隔帧，直接检查它们，编写审查后的逐结果 JSON，并使用 inktofilm run suite.json --semantic-results 重放它。仅对采样帧中可见的内容进行评分，并在结果来源中记录您自己的模型名称。
• 在 Codex 中，CLI 的内置集成通过经过身份验证的 Codex CLI 完成相同的工作：使用 inktofilm run --semantic-codex 进行评判，以及 inktofilm produce 的默认规划者和评判者。
• 当用户希望运行无人值守地完成时，将评判交给 CLI 而不是在循环中执行：使用 inktofilm run --semantic-claude，或 inktofilm produce --judge-claude，这只需要 Claude Code 和 fal 密钥。当您已经在场时，优先在循环中进行评判，因为它只花费一个模型而不是两个，并且您可以注意到任何断言没有要求检查的内容。
• 任何其他模型都可以通过 JSON 标准输入/输出钩子接入：--semantic-command、--planner-command、--judge-command 和 --video-command。
• 无论哪个评判者运行，它只对计划编写的断言进行评分。为实际出现的失败编写断言，包括发明的屏幕文本、烘焙在帧中的信箱模式、向错误文化漂移的服装，以及与场景矛盾的表达。

分阶段工作流程

inktofilm produce 是可恢复的：已经存在于输出目录中的肖像、静止图像和镜头尝试将被重用，因此相同的命令可以在审查后再次运行，并且只为缺失的工作付费。

1. 自己编写 script.md 和 plan.json，然后 inktofilm produce script.md --plan plan.json --stills-only -o <project>。这会为每个角色渲染一个肖像，为每个镜头渲染一个静止图像，然后停止。打开每个图像。一个不是角色的肖像、一个构图错误的静止图像、一张年龄错误的脸、一个多余的人或道具上的文字，在这里修复很便宜，在剪辑中修复则很昂贵：删除文件，优化其提示，并再次运行相同的命令。
2. 当您将在循环中评判时，使用 --no-judge 拍摄；当运行无人值守时，使用 --judge-claude。--no-judge 运行媒体检查，选择每个镜头的最新尝试，为选定的剪辑编写 suite.json，并组装一个简单剪辑的 final.mp4。
3. 对于每个镜头，inktofilm frames shots/<shot>-attempt-1.mp4 采样评判者会看到的帧。查看它们，编写审查后的结果文件，并使用 inktofilm run suite.json --semantic-results reviewed.json -o review 重放它。
4. 仅重新生成失败的镜头：--reshoot <shot_id> 为该镜头提供一次新的尝试，编号在磁盘上的尝试之后，并且其他所有内容都被重用。当失败是由于提示的过错时，先编辑提示。将新的镜头与旧的进行比较，而不是假设它更好；当较早的镜头获胜时，--select <shot_id>=<attempt> 使其再次成为该镜头的剪辑，因此清单、suite.json 和 final.mp4 都遵循审查者的选择。
5. 当电影需要不仅仅是简单剪辑时，自己使用 FFmpeg 组装最终剪辑：重叠、声音桥接、对话和本地排版标题卡。

编写能在生成中存活的提示

• 每个视频提示中的角色手册仅涵盖镜头列出的角色，因此列出它们。一个描述整个演员表的单人镜头往往会将其他人置于背景中。
• 参考肖像按照镜头 characters 的顺序传递给静态图像编辑器。在静态图像提示中按该顺序引用它们，例如“来自第一张参考图像的女人”，并无论如何重申她的头发、皮肤和服装；参考修复身份，文字修复画面。
• 将静止图像描述为照片：构图、每个人在哪里、他们在镜头打开瞬间正在做什么、光线、镜头。在可能携带文字的任何东西上说“无文本”，例如桨、标志或屏幕，并以“填满整个画面边缘到边缘，无黑条，无信箱”结束每个静止图像提示：否则宽幅建立镜头会返回带有烘焙在图像中的影院黑条，然后视频会继承这些黑条。
• 肖像会变得比编写的老和整洁。给出两次年龄（“25岁，看起来是二十五岁而不是更老”），按长度和行为描述头发（“顶部五厘米，梳向一侧，不是后梳，不是平头”），并命名电影其余部分使用的光线和调色板，否则一个孤立的镜头会以与相邻镜头不同的色温返回。
• 当静止图像被拒绝时，将其移动到旁边的一个 rejected/ 文件夹中，而不是删除它。重新运行只渲染缺失的内容，如果新镜头失去了正确的构图，旧的镜头仍然可用。
• 当镜头有静止图像时，以“正好在提供的帧上开始”打开视频提示，并说明谁保持相同的脸、头发和服装。命名不能增加的道具数量。
• MiniMax H3 Max 生成原生声音和唇形同步语音。对于一句台词，在提示中引用确切的词语，命名说话者，并要求自然的嘴唇运动和没有字幕；将相同的词语放在计划的 dialogue 字段中，以便评判者可以检查它们。可接受的持续时间是每个镜头 5 到 15 秒，分辨率为 480P 或 768P；两行对话需要六秒而不是五秒。帧无法确认说了什么，因此转录原生音频（一个本地 whisper.cpp 就足够了）并与剧本进行比较；该模型也会在人群场景中即兴喃喃的台词，因此阅读整个转录，而不仅仅是您写的台词。
• 光线“捕捉”或“反射在”角色眼睛中会被字面渲染为发光的虹膜。说明眼睛保持其自然颜色，并禁止其中有色光。
• 两个手持道具在几帧内往往会合并到一只手中，无论静止图像显示什么。当一个道具很重要时，给它一个不是手的地方（嘴、口袋、桌子）或计划让它成为可选的，并根据舞台效果而不是哪只手拿着什么来评判镜头。
• 以一个看向下一个镜头主体的视线方向（在切换到她转身之前，看一眼前排）结束一个镜头，这样连接被理解为因果关系，而不是两个独立的生成。
• 在 FFmpeg 组装中，concat 发出一个微秒级的时间基准，后续的 xfade 会拒绝该基准；在混合溶解和硬剪辑时，在 concat 之前和之后将每个视频链固定为 settb=1/<fps>。将每个剪辑修剪到其计划长度，以便标题卡保持其完整运行，并从文件中读取剪辑持续时间，而不是假设它们。
• 以电影摄影师而不是舞台管理员的身份编写视频提示。以媒介和物理属性开头，然后再进行任何调度：“逼真的真人 <类型> 电影，不是动画，不是游戏过场动画”，镜头、光线来源、空气在做什么（薄雾、霜尘、雨），以及“物理上可信的布料、头发和重量”。一个主要是调度和禁止的提示（“保持坐着”、“没人离开他们的位置”、“与第一帧相同的脸”）会返回一个抽搐的照片：模型动画它被告知要动画的内容并冻结其余部分，静止读起来像假的。在一个子句中命名必须保持稳定的内容（一把剑，两张脸），而不是五个。
• 给每个动作一个时钟：“在前半秒内”、“在中点”、“在最后一秒”。未定时的动作要么永远不会到达，要么花在预备动作上，而没有定时节拍的动作会以缓慢推进到保持姿势的人身上结束。
• 对于有打斗镜头的电影，永远不要在 visual_style 中写“慢动作”或“优雅、从容”：样式会在每个镜头上重述，因此每个交锋都会以漂浮方式到达，打斗没有节奏。在风格中说“实时速度”，并在打斗提示内构建节奏：计数交锋次数（“在前两秒内三次劈砍和三次格挡”），命名停止（“刀刃锁住，一个保持的节拍”），然后释放（“她打破锁，下一轮更快”），并让速度变化只存在于一个冲击处。对比读起来像节奏；统一的优雅读起来像慢。
• 向下退出读起来像坠落。一个“从屋檐上跨出并掉入薄雾中”的角色会被观众视为从建筑物跳下的人，无论提示使其多么轻盈。在屋顶上结束一个屋顶场景（一个祝酒、一把入鞘的剑、一个眼神），或者将下降放在一个单独的镜头中，并有一个可见的着陆带有重量。
• 能在观众中存活的对话是戏剧性对话，而不是格言。两个对称的警句（“霜是冷的，酒不是”）听起来像是写出来的；一个有转折的简单交流听起来像是说出来的。当用户命名他们喜欢的场景时，借用那个场景的交流逻辑（一个陈述的规则，一个利用的漏洞，一个简短的命令，一个厚颜无耻的拒绝），并以您自己的角色自己的语气说出来，然后保持每行足够短，以便在您给它的秒数内说完。
• 为宽幅、风景、动作和规模镜头选择文本到视频。模型拥有运动，剪辑读起来像拍摄的。为那些必须匹配静止图像的脸或确切构图的镜头保留图像到视频，并且在那里也要前置动作。一个精致的静止图像对于运动来说是一个负担：照片越整洁，剪辑就越像一张照片在醒来。当用户更喜欢令人信服的运动而不是相同的脸时，在计划中说明：将 still_prompt 和 reference_prompt 留空，并在每个角色的 description 中携带身份，生产提示会在列出该角色的每个镜头上逐字重述该描述。
• 通过源而不是文件大小来评判编码。比较原始提供商剪辑的比特率与组装电影的比特率：在相同编码器设置下，最终数字低得多意味着剪辑是静态的，而不是编码有损。使用 -preset slow 以 CRF 16 或更低组装，保持提供商的帧尺寸（不要在任何方向重新缩放 768P 剪辑），并在用户询问后期是否损失质量时在交付说明中说明这一点。
• 在将对话镜头修剪到其计划长度之前，从转录中读取词语时间戳（whisper-cli -ml 1），并保持剪辑足够长，使得最后一个词在输出音频淡出开始之前结束；一条持续到剪辑末尾的台词如果语音在溶解期间没有被音频保护，则可能会失去其最后一个音节。重新转录组装电影的对话窗口，而不仅仅是原始剪辑。
• 没有语音的剪辑的转录不是语音的证据。whisper 会在稳定的环境音上发明简短台词和字幕致谢；在为了“即兴”台词重新拍摄之前，使用时间戳和响度包络确认它（语音显示为环境音底噪之上的峰值）。
• 从参考肖像编辑的静止图像继承肖像的脸，但发明天气。在每个静止图像提示中固定天空、降水和季节（“晴朗的夜晚，瓷砖上的霜，没有雪”），否则一个单一的脸匹配特写会在电影其余部分没有雪的情况下以雪景返回。