소개
이 페이지에서는 alpha2가 하는 일과 구성 요소가 맞물리는 방식, 그리고 어디서부터 시작하면 되는지를 설명합니다. 다 읽고 나면 내 앱에 어떤 패키지가 필요하고 내 코드가 무엇을 맡아야 하는지 알 수 있습니다.
alpha2란
섹션 제목: “alpha2란”alpha2는 WebAssembly와 네이티브 환경에서 모두 동작하는 범용 미디어 엔진입니다. 소스, 비디오·오디오·자막(caption) 트랙, 클립, 이펙트, 트랜지션으로 이루어진 타임라인 프로젝트를 GPU로 렌더링하며, 프리뷰와 export 모두에 쓰입니다.
아래 프리뷰는 지금 이 브라우저에서 엔진이 직접 렌더링하는 실제 프로젝트입니다. 사진 세 장을 방향 와이프와 페이드로 이어 붙였습니다.
핵심 아이디어: 프로젝트 하나, 같은 프레임
섹션 제목: “핵심 아이디어: 프로젝트 하나, 같은 프레임”프로젝트는 JSON 문서입니다. 어떤 소스를 쓰는지 밝히고, 트랙 위에 클립을 놓고, 언제 어떤 이펙트와 트랜지션을 적용할지 적습니다. 형식에는 버전이 있고("schema_version": 1) JSON Schema로 기술되어 있으므로, 코드로 생성하고, 저장하고, diff를 보고, 렌더링 전에 검사할 수 있습니다.
모든 대상 환경이 같은 렌더링 코드를 실행합니다. 브라우저에서는 WebAssembly 빌드가, 서버에서는 네이티브 호스트가, 여러분의 프로그램에서는 Rust 크레이트가 같은 코드를 돌립니다. 그래서 하나의 프로젝트가 브라우저 프리뷰에서도, 서버 export에서도, Rust 프로그램에서도 똑같이 렌더링됩니다. “똑같다”가 정확히 무엇을 뜻하고 어디까지인지는 결정론에서 설명합니다.
프로젝트 안의 시간은 모두 틱(tick) 단위의 정수이며, 1초는 120,000틱입니다. 그 이유는 시간과 틱에서 다룹니다.
패키지
섹션 제목: “패키지”| 만들려는 것 | 사용할 패키지 |
|---|---|
| 미디어 디코딩과 인코딩을 직접 하면서 프리뷰와 export를 하는 브라우저 앱 | alpha2 (npm) |
| 문서, 커맨드, 실행 취소, 프리뷰·export 브리지를 갖춘 브라우저 에디터 | @alpha2-sh/editor (npm) |
alpha2 브라우저 플레이어를 감싼 React 캔버스 |
@alpha2-sh/react (npm) |
| Node.js나 Electron에서 MP4, MOV, MKV, WebM export | @alpha2-sh/node (npm)와 alpha2-host |
| 그 밖의 언어에서 MP4, MOV, MKV, WebM export | alpha2-host serve와 stdio 프로토콜 |
| Python에서 프로젝트 생성, 검증, export | alpha2 (PyPI) |
| Rust 프로그램 | alpha2 (크레이트) |
자세한 비교는 대상 환경 고르기를 참고하세요.
누가 무엇을 하는가
섹션 제목: “누가 무엇을 하는가”엔진은 렌더링을 합니다. 엔진 자체는 미디어 파일을 읽거나 쓰지 않으므로, 대상 환경마다 디코딩과 인코딩은 다른 쪽이 맡습니다.
브라우저에서는 앱이 미디어를 디코딩해서 픽셀과 샘플을 업로드합니다. 정지 이미지는 uploadRgbaImage, WebCodecs VideoFrame은 uploadVideoFrame, 오디오는 uploadAudioBlock을 씁니다. 엔진은 특정 시각에 필요한 프레임을 정확히 알려 주고(frameNeeds), 캔버스에 프레임을 그리며(renderAt), export할 때는 각 프레임을 planar I420으로, 오디오는 믹스된 상태로 돌려줍니다. 인코딩은 앱이 합니다. 예를 들어 alpha2/mediabunny의 MediabunnySink를 통해 WebCodecs로 인코딩할 수 있습니다.
네이티브에서는 alpha2-host가 세 가지를 모두 합니다. FFmpeg 8로 디코딩과 인코딩을 하고, GPU(Vulkan, Metal, Direct3D 12)로 렌더링하며, GPU가 없으면 CPU로 렌더링합니다. @alpha2-sh/node, Python 패키지, CLI가 모두 이 호스트를 실행합니다.
Rust에서는 프로그램이 FrameProvider를 통해 디코딩한 프레임을 엔진에 빌려주고, 렌더링된 프레임과 YUV 플레인을 돌려받습니다. 필요하면 alpha2-native로 FFmpeg 디코딩과 인코딩을 할 수 있습니다.