fframes: 빠르고 실제적인 비디오 코딩 프레임워크

빠르면서 실제로 작동하는 비디오 바이브 코딩 프레임워크.

Rust와 SVG로 동영상을 작성하고 GPU에서 렌더링하세요.

이 128초짜리 영상은 48분 만에 '바이브'되었고, 36초 만에 렌더링되었습니다. 이것은 fframes 프로젝트의 예시입니다: examples/fframes-intro.

fframes는 코딩 에이전트를 위한 스킬을 제공합니다. 한 번만 추가하세요:

npx skills add https://fframes.studio

그런 다음 원하는 비디오를 설명하세요. 마치 모션 디자이너에게 브리핑하듯이 말입니다. 이 스킬은 빈 폴더에 있던 에이전트를 렌더링된 .mp4 파일까지 데려다줍니다.

: fframes를 설치하고, 프로젝트를 생성하며, 모션을 디자인하고, 사운드를 배치하고, 결과를 확인한 후 사용자에게 전달합니다.

fframes API는 명시적이고 장황(verbose)하여 오랫동안 공개되지 않았습니다. 명시적이고 장황한 코드를 작성하는 것이 바로 적절한 스킬을 가진 에이전트가 잘하는 일입니다.

코딩 에이전트는 비디오를 보거나 사운드트랙을 들을 수 없습니다. 생성되는 모든 프로젝트에는 비디오를 에이전트가 읽을 수 있는 것들(PNG, 텍스트, 숫자)로 변환하는 명령줄이 포함됩니다.

|

모든 명령어는 프로젝트 내부에서 cargo run --release -- <명령어>로 실행됩니다:

<장면>은 비디오 내 장면 구조체(scene struct)의 이름입니다. 시간은 120(프레임), 3.2s, 50%, <장면>@1.2s와 같이 읽힙니다. 범위는 <장면>@0..<장면>@1s와 같습니다. 출력을 파싱하려면 --json을 추가하세요.

GPU가 그립니다. Skia 백엔드는 Metal (macOS) 또는 Vulkan (Linux, Windows)에서 렌더링하며, 내장 CPU 백엔드보다 약 10배 빠릅니다.정적 마크업은 캐시됩니다. {expressions}가 없는 프레임의 일부는 컴파일 시간에 해싱되어 렌더러에 의해 재사용됩니다.**ffmpeg 인코딩.**fframes는 별도의 도구를 호출하는 대신 ffmpeg의 libav 라이브러리를 연결합니다.**SVG로 충분하지 않을 때의 셰이더.**SkSL 또는 붙여넣은 Shadertoy GLSL을 모든 프레임의 레이어로 실행할 수 있습니다.

모든 프레임은 Rust 함수에 의해 반환되는 SVG 트리이며, svgr! 매크로를 사용하여 작성되었습니다. examples/hello-world에서 가져온 간소화된 예제는 사각형이 타임라인을 따라 움직이고 텍스트 라인이 현재 프레임을 출력하는 내용입니다.

코드 보기

impl Video for HelloWorldVideo<'_> {
const FPS: usize = 30;
const WIDTH: usize = 1920;
...

이 스킬의 가이드들은 일반 마크다운으로 작성되었으며, 워크플로우, API 치트 시트, 디자인 및 사운드 등 사람이 읽기에도 가치가 있습니다. 전체 API 레퍼런스는 docs.rs/fframes에서 확인할 수 있습니다.

cargo install --locked cargo-fframes
cargo fframes new my-video
cd my-video && cargo run --release -- preview

cargo fframes new는 다음을 받습니다:
--template single-scene|multi-scene
, --format landscape|portrait|square|uhd
, --fps
,
--title
그리고 --backend.
macOS와 Linux (arm64, x86_64)의 경우 첫 빌드는 사전 구축된 Skia 및 ffmpeg 라이브러리를 다운로드하며 빠른 기기에서는 1분 이내에 완료됩니다. 다른 타겟이나 기능 조합은 소스에서 컴파일합니다(최대 약 20분). 이후 빌드는 몇 초가 걸립니다. --backend cpu는 Skia를 건너뜁니다 (미리보기 창 없음, 느린 렌더링). main을 추적하려면 다음으로 설치하세요:
--git https://github.com/dmtrKovalenko/fframes.

Rust와 에디터 작업을 위한 NodeJS가 사용됩니다. fframes는 ffmpeg의 libav 라이브러리를 정적으로 연결합니다. macOS 및 Linux (arm64 및 x86_64)용 사전 구축 빌드가 다운로드되며, 다른 타겟이나 FFMPEG_FORCE_BUILD=1을 통해 소스에서 컴파일됩니다;
어느 쪽이든 시스템 인코더는 연결되어야 합니다.

예제들은 네이티브 비-Windows 타겟에서 fframes/build-portable을 활성화합니다. CI는 전체 워크스페이스를 빌드하며, 예시들의 x264, x265, VPX 및 Opus 기능을 결합합니다. 현재 게시된 FFmpeg 아카이브 중 이 조합과 일치하는 것이 없기 때문에 소스 빌드로 폴백(fallback)됩니다. build-portable이 없는 경우, 해당 빌드는 -march=native -mtune=native를 사용합니다. 이를 캐싱하고 다른 CPU를 사용하는 러너에서 복원하면 SIGILL(잘못된 명령어)을 유발할 수 있습니다.

이 기능은 소스 빌드 시 해당 플래그들을 생략하는 동시에 일치하는 사전 구축 다운로드를 활성화 상태로 유지하며, 컴파일 타임 미디어 매크로에 사용되는 FFmpeg에도 적용됩니다.

이 워크스페이스 내에서는 캐싱되거나 다른 장비에서 실행될 네이티브 빌드와 동일한 설정을 사용하세요:

[target.'cfg(not(any(target_arch = "wasm32", windows)))'.dependencies]
fframes = { workspace = true, features = ["build-portable"] }

build-portable

also enables FFmpeg의 소스 빌드 지원을 활성화하므로 예제에서는 Windows(공유된 FFmpeg 설치를 연결하는)와 브라우저 타겟은 제외합니다. FFMPEG_MARCH 또는 FFMPEG_MTUNE에 빈 문자열로 설정하면 사전 구축된 다운로드 과정을 우회합니다. 포터블 소스 폴백과 사전 구축된 다운로드 모두를 원할 경우 해당 기능을 사용하는 것이 좋습니다.

macOS

brew install pkg-config ffmpeg x264 x265 opus nasm ninja

Linux

데비안 기반 배포판의 경우:

sudo apt-get install -y yasm nasm ffmpeg libx264-dev libx265-dev libopus-dev libclang-dev clang ninja-build libvpx-dev libasound2-dev

아치 기반 배포판의 경우:

sudo pacman -S ninja yasm nasm ffmpeg x264 x265 opus clang

Nix 사용자의 경우:

nix-shell

Windows

Windows에서는 ffmpeg을 소스에서 컴파일하지 않습니다. 대신 fframes는 사전 구축된 FFmpeg 9.0 공유 빌드(예: BtbN/FFmpeg-Builds의 ffmpeg-n9.0-latest-win64-gpl-shared-9.0.zip)를 연결하며, bindgen을 위해 LLVM이 필요합니다:

winget install LLVM.LLVM
# ffmpeg 빌드를 어딘가에 압축 해제한 후, 빌드 경로를 지정합니다:
$env:FFMPEG_DIR = "C:\ffmpeg-n9.0-latest-win64-gpl-shared-9.0"
...

vcpkg install ffmpeg도 FFMPEG_DIR 대신 작동합니다.

코덱은 사전 구축된 빌드에서 오기 때문에, 코덱 기능(h264, h265, ...)은 제외하세요. 이들은 Windows에서 지원되지 않는 소스 기반의 ffmpeg 빌드를 요청하기 때문입니다.

코덱

fframes 크레이트의 Cargo 기능은 연결할 코덱과 하드웨어 가속 라이브러리를 선택합니다:

[dependencies]
# 이는 빌드 중에 libx264를 활성화하고 연결을 시도합니다
fframes = { version = "1", features = ["h264", "libav-agree-gpl"] } 

코덱 및 기타 시스템 라이브러리의 모든 빌드와 연결은 ffmpeg 빌드 시스템을 활용하므로, 문제 해결이 필요하면 ffmpeg 컴파일 가이드를 참조하세요.

문제 해결

위 목록의 시스템 라이브러리 중 하나가 누락되어 빌드에 실패합니다 (ffmpeg-sys-fframes:nasm, pkg-config, 코덱 패키지). Skia 바인딩에서 bindgen 또는 libclang 오류가 발생하여 빌드에 실패합니다 (Skia를 소스에서 컴파일할 때만 해당, 예를 들어 metal과 vulkan 모두 활성화된 경우): 작동하는 libclang의 경로를 macOS Xcode에서 지정하세요: export LIBCLANG_PATH=$(xcode-select -p)/Toolchains/XcodeDefault.xctoolchain/usr/lib. 텍스트가 잘못된 글꼴로 렌더링됩니다: inspect는 No match for ... font-family를 보고합니다; 글꼴 파일을 프로젝트의 media/ 폴더에 넣고 정확한 패밀리 이름을 사용하세요.

fframes 자체에서 작업하는 에이전트는 AGENTS.md부터 시작해야 합니다. 인간 개발자의 경우, just 명령 실행기를 설치하고 리포지토리를 초기화하세요:

npm install --global pnpm # nodejs 기반 편집기의 패키지 매니저
cargo install --locked just cargo-watch wasm-bindgen-cli wasm-pack
just init-repo
...

fframes는 MIT 라이선스 하에 배포됩니다.