sionrui/openspec/changes/add-ice-916-crop/design.md

Context

混剪功能需要将多种比例的素材统一输出为 9:16 竖屏视频（720x1280）。 阿里云 ICE 支持视频裁剪和缩放，需要在 Timeline 中配置正确的参数。

Goals / Non-Goals

Goals:

• 支持横屏 (16:9) 素材自动裁剪为竖屏 (9:16)
• 支持多种裁剪模式（居中、智能、填充）
• 保持视频质量，避免过度拉伸

Non-Goals:

• 不实现自定义裁剪区域选择
• 不实现实时预览

Decisions

裁剪模式设计

模式	说明	适用场景
center	居中裁剪，保持原始比例	主体在画面中央
smart	智能裁剪（ICE AI 识别主体）	人物/产品展示
fill	填充黑边，不裁剪	保留完整画面

ICE 参数方案

方案 A：使用 CropX/CropY/CropW/CropH

{
  "MediaURL": "xxx",
  "CropX": 280,
  "CropY": 0,
  "CropW": 720,
  "CropH": 1280
}

方案 B：使用 Effects + Crop

{
  "Effects": [{
    "Type": "Crop",
    "X": 280,
    "Y": 0,
    "Width": 720,
    "Height": 1280
  }]
}

裁剪计算公式

对于 16:9 横屏素材 (1920x1080) 裁剪为 9:16：

目标比例 = 9/16 = 0.5625
源比例 = 16/9 = 1.778

// 居中裁剪
cropHeight = sourceHeight = 1080
cropWidth = cropHeight * (9/16) = 607.5 ≈ 608
cropX = (sourceWidth - cropWidth) / 2 = (1920 - 608) / 2 = 656
cropY = 0

Risks / Trade-offs

• 画面损失：居中裁剪会丢失左右两侧内容
• 缩放失真：填充模式会缩小画面
• ICE 兼容性：需确认 ICE 版本支持的参数

Open Questions

1. ICE 是否支持智能主体识别裁剪？
2. 是否需要前端预览裁剪效果？
3. 默认裁剪模式选择哪种？