https://github.com/antirez/h3.c
내용이 길어서 Perplexity 에게 써달라고 했습니다. ㅎ

암튼 저는 내일이나 M5 Air 32G 에서 돌려보려고 합니다.

github 에서 issue 에 가면 M5 Air 32G 로 돌려본 사람 사용기가 있더군요.

antirez의 h3.c, MiniMax H3를 맥에서 직접 돌리는 C+Metal 엔진 소개와 사용기

최근 GitHub에 공개된 h3.c는 Redis로 유명한 antirez(살바토레 산필리포)가 만든 MiniMax H3 비디오·오디오 생성 모델용 네이티브 추론 엔진입니다.[cite:26][cite:4]
파이썬·PyTorch·ComfyUI 같은 무거운 스택 없이, 순수 C + Metal + 약간의 Objective‑C와 Metal 셰이더만으로 Apple Silicon Mac에서 H3를 직접 돌리는 것이 핵심입니다.[cite:26][cite:5]

공식 README의 첫 문장은 이 프로젝트를 이렇게 정의합니다.

Native MiniMax‑H3 inference for Apple Silicon.[cite:26]

즉, 목표는 “Mac에서 MiniMax H3를 가능한 한 직접, 빠르게, 정확하게” 돌려보는 것입니다.

h3.c가 하는 일

MiniMax H3는 텍스트를 입력하면 비디오와 오디오를 동시에 생성하는 멀티모달 확산 모델입니다.[cite:4][cite:11]
h3.c는 이 모델을 맥에서 다음과 같은 방식으로 실행합니다.

• 텍스트 → 비디오 + 사운드
  한 줄 프롬프트로 영상과 내장 오디오를 동시에 생성합니다.[cite:5][cite:6]

• 첫/마지막 프레임 앵커(FL2VA)
  오프닝 스틸컷과 엔딩 스틸컷 이미지를 넣으면, 그 사이를 H3가 자연스럽게 이어주는 “키프레임 기반 연장” 생성이 가능합니다.[cite:26][cite:28]

• Ref2VA 레퍼런스 모드
  여러 장의 이미지, 기존 영상, 오디오 클립을 순서대로 참고 자료로 던져서 , , 같은 토큰으로 스타일·구도·모션을 유도할 수 있습니다.[cite:5][cite:27]

• 인터랙티브 Iris 스타일 CLI 세션
  한 번 모델을 올려놓으면, 동일 프롬프트·조건에서 시드만 바꿔가며 연속 실험이 가능한 터미널 기반 인터랙티브 세션을 제공합니다.[cite:5][cite:4]

엔진 자체는 MIT 라이선스로 공개되어 있어, 코드 수정·재배포·상업적 이용이 모두 허용되지만, MiniMax H3 가중치는 Hugging Face에 별도 라이선스로 배포되는 점은 반드시 확인해야 합니다.[cite:4][cite:27]

환경과 빌드

필요한 환경은 생각보다 단순합니다.

• 필수 하드웨어/소프트웨어

  • Apple Silicon Mac (README와 외부 사용기는 M3, M5 Max 기준으로 튜닝/측정).[cite:11][cite:27]

  • MiniMax‑H3 체크포인트(FL2VA/Ref2VA 트리)를 Hugging Face에서 받아 ./MiniMax-H3 폴더에 배치.[cite:26][cite:28]

  • FFmpeg / FFprobe가 PATH에 있어야 비디오·오디오 입출력을 처리할 수 있습니다.[cite:26][cite:5]

• 빌드 및 기본 체크

README 기준으로 기본 빌드 및 정보 확인 과정은 다음과 같습니다.[cite:26][cite:28]

git clone https://github.com/antirez/h3.c.git
cd h3.c

make -j8
mkdir -p outputs

./h3 --info -d ./MiniMax-H3

--info 플래그는 전체 모델 레이아웃과 선택된 Metal 디바이스를 검사하는 용도로, 가중치를 전부 매핑하거나 실제로 영상을 생성하진 않습니다.[cite:26]

실제 생성: 비대화형 vs 인터랙티브

비대화형 한 번 생성

README에서 “밸런스 프리셋”이라고 소개하는 조합은 대략 다음과 같습니다.[cite:26][cite:6]

• 해상도: 512×512

• 프레임: 22 (약 0.9초)

• 디노이징 스텝: 20

• 활성 DiT 레이어: 45

• --reuse 2 (20개 중 11스텝만 실제 디노이저 forward, 나머지는 외삽)

예시 커맨드는 다음과 같은 형태입니다.

./h3 --profile \
  -d ./MiniMax-H3 \
  -p "A red fox walks through fresh snow in a pine forest..." \
  --width 512 --height 512 \
  --frames 22 --steps 20 \
  --layers 45 --reuse 2 \
  --show \
  -o outputs/fox-fast.mp4

--show를 붙이면 Kitty/Ghostty/iTerm2/WezTerm/Konsole 같은 그래픽 터미널에서 매 디노이징 스텝마다 중간 프레임과 최종 시퀀스를 미리 볼 수 있습니다.[cite:26][cite:6]

인터랙티브 세션

프롬프트 없이 실행하면 Iris 스타일 CLI 세션이 시작됩니다.[cite:26][cite:5]

./h3 -d ./MiniMax-H3 --width 512 --height 512 --steps 6

이 상태에서 프롬프트 문장을 입력하면 번호가 붙은 비디오 파일이 순차적으로 생성되고, 세션 내에서 다음과 같은 명령을 사용할 수 있습니다.[cite:5]

• !status – 현재 세션 상태 출력

• !seed random – 시드를 랜덤으로 변경

• !seconds 2 – 길이를 초 단위로 설정

• !show – 프리뷰 프레임 표시

• !save output.mp4 – 현재 결과를 파일로 저장

• !cache – 준비된 상태를 캐싱해 재사용

• !first PATH, !last PATH – 첫/마지막 프레임 앵커 설정

• !ref-image PATH – Ref2VA 이미지 레퍼런스 추가

이 방식은 “한 번 올린 프롬프트 조건과 DiT·VAE를 메모리에 유지한 채 시드만 바꿔가며 반복 실험하는” 워크플로에 적합합니다.[cite:5][cite:4]

품질과 속도: 튜닝 노브들

h3.c의 README는 거의 온디바이스 추론 튜토리얼에 가까울 정도로 상세하게, 품질과 속도를 바꾸는 축들을 정리하고 있습니다.[cite:12][cite:27]

대표적인 노브들을 몇 가지로 요약하면:

디노이징 스텝 수 (--steps)

• 4–7 스텝

  • 512×512·22프레임 기준, 4스텝 경로는 M5 Max에서 약 3.5초에 끝납니다.[cite:6][cite:11][cite:27]

  • 같은 클립을 29패스 레퍼런스 경로로 돌리면 26.4초라, “디테일은 줄지만 프리뷰/반복 실험에 최적화된 모드”로 설명됩니다.[cite:12][cite:27]

• 20 스텝

  • 디폴트 값으로, 품질과 속도의 균형이 잡힌 경로입니다.[cite:26]

• 50 스텝

  • “참조 오라클”로, 빠른 모드에서 구도·인체·모션이 얼마나 망가졌는지 비교할 때 쓰라고 README에서 권장합니다.[cite:26][cite:28]

레이어 수 (--layers)

• 50 레이어 – 전체 DiT 블록 사용, 가장 보수적인 품질 기준.[cite:26][cite:2]

• 45 레이어 – 중간 레이어 일부를 게이트 기반으로 제거하는 “레이어 thinning” 모드로, compute와 메모리를 줄이면서 품질을 상당 부분 유지합니다.[cite:26][cite:6]

• 40 레이어 – 더 공격적인 프리뷰 용으로, 속도와 메모리 절감 폭이 크지만 품질 저하 가능성이 큽니다.[cite:26]

전체 디노이저 재사용 vs 코어 재사용

• --reuse N

  • 첫/마지막 스텝과 N 간격마다 디노이저 전체를 실제로 평가하고, 중간 스텝은 외삽으로 채우는 구조입니다.[cite:26][cite:3]

• --core-reuse N

  • 코어 residual만 들고 있고, 패치·헤드 부분은 매 스텝 새로 계산하는 모드입니다.

  • --reuse와는 상호 배타적이라 두 옵션을 동시에 쓸 수 없습니다.[cite:26]

토큰 리덕션 (--token-reduction)

• 중간 블록 이후 영상 토큰을 가로 방향으로 둘씩 묶어 tail 구간에서 계산량을 줄이고, 나중에 원래 해상도로 복원하는 구조입니다.[cite:26][cite:6]

• 512×512·50블록 기준에서 39.13초 → 28.06초(약 28% 단축)라는 README 수치가 대표적으로 인용됩니다.[cite:12][cite:27]

• 다만 구도와 세부 디테일이 변할 수 있어서, 기본값이 아니라 “옵션”으로 남겨둔 상태입니다.[cite:6][cite:27]

내부 캔버스 스케일링 (--render-width, --render-height)

• 512×512를 목표로 하되, 내부 DiT/VAE는 384×384 또는 320×320에서 돌리고 마지막에 vImage로 업스케일하는 방식입니다.[cite:26][cite:6]

• README 기준으로 384 내부 렌더는 DiT 시간이 약 33%, VAE 시간은 18% 줄면서도, 실사 계열 결과가 “깨끗하고 인식 가능한 수준”으로 나왔습니다.[cite:26][cite:28]

해상도와 길이 제약

MiniMax H3는 24fps 기반으로, 유효한 프레임 수가 5 + 17n 형태로만 허용됩니다.[cite:11][cite:26]
README와 외부 기사에서 대표적으로 정리된 조합은 다음과 같습니다.[cite:26][cite:28]

• 22프레임 – 약 0.92초

• 39프레임 – 약 1.63초

• 56프레임 – 약 2.33초

• 107프레임 – 약 4.46초

• 243프레임 – 약 10.1초

• 362프레임 – 약 15.1초

해상도는 폭·높이가 각각 32의 배수이고, 둘의 곱이 768 × 1344를 넘으면 안 됩니다.[cite:6][cite:11]
유효한 캔버스로 반복 검증된 조합은 512×512, 768×768, 1344×768, 768×1344, 1024×768, 768×1024, 그리고 256×256 네이티브 프리뷰 캔버스입니다.[cite:6][cite:27]

256×256 모드는 RoPE 좌표를 자동으로 절반으로 줄이는 “fast preview” 모드로, 긴 폭스 렌더에서 반복 무늬 artifact를 없애면서 인물·포트레이트에서도 안정적인 구도를 유지했다는 실험 결과가 README에 실려 있습니다.[cite:26][cite:27]

성능과 메모리: 실제 수치

여러 기사와 README를 종합하면 h3.c의 성능·메모리 특성은 대략 다음과 같습니다.

• 4스텝 512×512·22프레임 클립

  • M5 Max 기준 약 3.5초에 끝나는 벤치가 README와 외부 블로그에서 반복적으로 인용됩니다.[cite:6][cite:11][cite:27]

  • 같은 클립을 29패스 레퍼런스 경로로 돌리면 26.4초 정도로, SSIM 약 0.55 수준에서 빠른 경로와 품질 차이가 측정되었습니다.[cite:12][cite:27]

• 20스텝 + 레이어 45 + reuse 2 프리셋

  • 512×512 기준 약 16.7초 정도로, 토큰 리덕션을 추가하면 12.60초까지 줄었다는 수치가 README에 정리되어 있습니다.[cite:6][cite:27]

• BF16 vs int8 전체 경로

  • 50층·512×512 기준 BF16 MPSGraph 경로는 36.30초, MLP를 int8로 바꾸면 25.80초, QKV까지 int8로 바꾸면 19.32초라는 벤치마크가 외부 글에서도 요약되어 있습니다.[cite:12][cite:4][cite:27]

• 메모리 사용량

  • H3 트랜스포머 체크포인트 자체가 약 33GiB이고, 전체 비디오+오디오 파이프라인을 돌릴 때 피크 물리 메모리가 약 40GiB에 도달한 것으로 README와 기사들이 전합니다.[cite:11][cite:28]

  • int8 경로를 사용하면 텐서 피크 저장 용량이 36.4GiB → 25.9GiB로 줄지만, 여전히 64–128GB급 Mac이 권장됩니다.[cite:12][cite:27]

라이선스와 법적 주의사항

중요한 점 하나는, 엔진 코드와 모델 라이선스가 분리되어 있다는 것입니다.

• h3.c 코드 자체는 MIT 라이선스로 공개되어 있어, 수정·재배포·상업적 이용이 가능합니다.[cite:4][cite:27]

• 그러나 MiniMax H3 가중치는 Hugging Face에서 별도 라이선스로 배포되고 있으며, EU, UK, 미국, 한국 등 특정 지역에서의 로컬 배포·상용 사용을 제한하는 조항이 포함되어 있다는 분석 글들이 있습니다.[cite:27][cite:28]

즉, “엔진을 구현한 사람”과 “가중치를 다운로드해서 실제로 돌리는 사람”의 법적 책임이 다르며, 해당 국가에서 연구·테스트 용도로 쓰더라도 라이선스를 꼼꼼히 읽고 준수해야 합니다.[cite:27][cite:28]

누가 쓸 만한 프로젝트인가?

영상·AI 쪽에서 h3.c는 꽤 특수한 위치를 차지합니다.
일반 사용자에게는 “준비된 Web UI로 버튼 한 번 눌러서 예쁜 영상 뽑는 도구”가 아니지만, 다음과 같은 사람들에게는 아주 매력적인 프로젝트입니다.

• Mac 기반 크리에이터·개발자

  • 별도의 GPU나 클라우드 없이, M3/M5 Max급 Mac 단일 머신에서 MiniMax H3 전체 비디오·오디오 파이프라인을 실험해 보고 싶은 경우.[cite:11][cite:27]

• 온디바이스 추론 최적화에 관심 있는 엔지니어

  • Metal 4/TensorOps, int8 양자화, RoPE/RMS fuse, activation alias, streamed text encoder 같은 최적화 패턴을 실제 코드와 벤치마크로 공부하고 싶은 경우.[cite:12][cite:27]

• 자기만의 비디오 엔진을 만들고 싶은 개발자

  • ComfyUI 같은 노드 기반 툴이 아니라, C/Metal 레벨에서 직접 비디오 생성 파이프라인을 설계·제어하고 싶은 경우, h3.c는 훌륭한 참고 구현체입니다.[cite:4][cite:6]

반대로, 단순히 “예쁜 결과 영상”만 빨리 뽑고 싶다면 굳이 Metal·C 레벨까지 내려갈 필요는 없고, 여전히 Web UI나 파이썬 툴들이 접근성과 플러그인 생태계 면에서 더 편리하다는 점도 함께 고려해야 합니다.[cite:5][cite:14]

개인적인 활용 상상

M5 Max + 96–128GB급 Mac이 있다는 가정에서, h3.c를 개인적으로 써본다면 워크플로는 대략 이렇게 잡을 수 있을 것 같습니다.

1. 256×256 네이티브 프리뷰로 구도와 동선만 빠르게 맞추기
   RoPE 최적화가 들어간 fast preview 모드에서 인물·카메라 워크를 먼저 검증합니다.[cite:26][cite:27]

2. 512×512·20스텝·레이어 45·reuse 2를 기본 경로로 사용
   토큰 리덕션과 내부 캔버스 축소(384/320)를 상황에 따라 켰다 껐다 하면서, 품질과 속도 사이에서 최적점을 찾습니다.[cite:6][cite:27]

3. 최종 샷은 50스텝 오라클로 품질 검증
   같은 프롬프트·해상도·프레임 수에서 50스텝 BF16/참조 경로를 한 번 돌려, 프리뷰 모드가 구도·인체·모션을 크게 망가뜨리지 않았는지 확인합니다.[cite:26][cite:12]

4. 레퍼런스 기반 연장 실험
   기존 실사 촬영 샷을 --ref-silent-video로 넣고, H3에게 모션만 이어받게 하거나,
   인물 사진 여러 장을 조건으로 걸어, 사진집 스타일의 비디오를 만드는 “스타일 모핑” 실험을 해볼 수 있습니다.[cite:26][cite:5][cite:27]

정리하자면, h3.c는 “현업에 바로 쓰는 영상 생성 툴”이라기보다는, 비디오 생성 모델의 내부를 뜯어보면서 Mac 온디바이스 성능을 끝까지 끌어쓰는 실험용 엔진에 가깝습니다.[cite:11][cite:12]
그 관점에서 보면, README와 코드만 읽어도 얻을 수 있는 인사이트가 많기 때문에, 온디바이스 LLM/비디오 모델 최적화에 관심 있는 사람이라면 한 번쯤 들여다볼 가치가 충분한 프로젝트입니다.[cite:12][cite:27]

▶ 원문 출처: https://github.com/antirez/h3.c