AIDC-AI/Pixelle-Video 딥다이브
— 주제 한 줄로 영상 한 편을 뽑는 파이프라인

1프로젝트 한줄 요약

Pixelle-Video가 노리는 지점이 정확히 여기다. "더 좋은 영상 생성 모델을 만든다"가 아니라 — 그건 이미 FLUX·WAN·Seedance 같은 전문 모델들이 하고 있다 — 그 모델들을 순서대로 엮어서 "주제 한 줄 → 완성 영상"이라는 사용자 경험을 완성하는 쪽으로 문제를 푼다. 진입 장벽 제로, 편집 경험 제로가 슬로건이다.

2왜 주목받는가

"MoneyPrinterTurbo 같은 자동 영상 도구는 이미 있는데 왜 또?"가 당연한 첫 반응이다. 실제로 README도 MoneyPrinterTurbo·NarratoAI·MoneyPrinterPlus를 참조 프로젝트로 밝히고 있다. 차별점은 "원자 능력(Atomic Capability)의 조합"이라는 설계 철학에 있다.

2-1. 대안들과의 정면 비교

2-2. "완전 무료 경로"가 존재한다

실무 채택에서 이게 크다. Pixelle-Video는 LLM을 로컬 Ollama로, 영상 생성을 로컬 ComfyUI로 돌리면 API 비용 0원으로 전체 파이프라인을 굴릴 수 있다. README FAQ가 이 "완전 로컬·무료" 경로를 명시한다. 반대로 GPU가 없으면 RunningHub(클라우드 GPU)나 DashScope·Seedance·Kling 같은 직접 API로 갈아타면 된다 — 같은 코드, 설정만 바꿔서.

2-3. 만든 곳이 알리바바 AIDC-AI

신뢰에 기여하는 요소다. 이미 Pixelle-MCP·ComfyKit 같은 오픈소스 생태계를 운영하는 조직이라, "AIGC 파이프라인용 완성형 제품"이라는 맥락이 자연스럽다. 게다가 FilmAgent(SIGGRAPH Asia 2024)·ComfyUI-Copilot(ACL 2025)·AniMaker(SIGGRAPH Asia 2025) 같은 논문 시리즈를 README가 함께 걸어둔다 — 단순 토이 프로젝트가 아니라 연구 기반 엔지니어링이라는 신호다. Docker 2-서비스 배포, Windows 올인원 패키지, 다국어 UI까지 실제 팀이 쓸 살이 붙어 있다.

3기술 스택 전체 지도

3-1. 핵심 엔진 (Python 3.11+ / pyproject + uv)

3-2. 프론트엔드 — Streamlit (별도 JS 프레임워크 없음)

흥미로운 선택이다. React·Vue 같은 SPA 프레임워크가 없다. 대신 Streamlit 멀티페이지 앱으로 UI를 짰다(web/app.py가 st.navigation으로 Home·History 두 페이지 구성). i18n은 web/i18n/locales/{en_US,zh_CN}.json으로 영어·중국어 지원. UI 파이프라인은 5종 — standard·asset_based·digital_human(디지털 아바타)·i2v(이미지→영상)·action_transfer(모션 트랜스퍼). 데이터 과학 도구인 Streamlit을 프로덕션 제품 UI로 쓴, "빠른 UI가 곧 경쟁력"이라는 판단이 읽힌다.

3-3. 백엔드 API — FastAPI

UI와 별개로 api/에 FastAPI 서버가 있다. 라우터가 기능별로 쪼개져 있다 — health · llm · tts · image · content · video · tasks · files · resources · frame. 비동기 태스크 매니저(api/tasks/)로 오래 걸리는 영상 생성을 백그라운드로 돌린다. 즉 Streamlit(사람용 UI)과 FastAPI(프로그램용 API)가 같은 엔진(pixelle_video 패키지)을 공유하는 이중 진입 구조다.

3-4. 모델은 어떻게 부르나 — 두 갈래

3-5. 인프라 / 배포

4아키텍처 심화 분석

이 장이 이 문서의 심장이다. 주제 텍스트 하나가 StandardPipeline에 들어가 완성 MP4로 나올 때까지 내부에서 벌어지는 일을 따라간다. 두 층위로 나뉜다 — 파이프라인 8단계(전체 흐름)와 그 안의 프레임 처리 4스텝(한 장면씩).

4-1. 중앙 오케스트레이터 — PixelleVideoCore

service.py의 전역 싱글턴 pixelle_video가 모든 것의 진입점이다. initialize()에서 LLM·TTS·미디어 서비스를 만들고 파이프라인 3종(standard·custom·asset_based)을 등록한다.

# pixelle_video/service.py — 서비스와 파이프라인을 한곳에 묶는다
self.pipelines = {
    "standard": StandardPipeline(self),
    "custom": CustomPipeline(self),
    "asset_based": AssetBasedPipeline(self),
}
pixelle_video = PixelleVideoCore()  # 전역 싱글턴

4-2. 상태를 나르는 그릇 — PipelineContext

8단계가 서로 데이터를 주고받는 방식이 깔끔하다. 각 단계가 전역 변수를 건드리는 대신, 하나의 PipelineContext dataclass를 단계에서 단계로 넘긴다. 앞 단계가 채운 필드(나레이션·제목·스토리보드)를 뒤 단계가 읽는다. 예외가 나면 handle_exception이 한곳에서 처리한다. 상태가 한 객체에 모여 있으니 디버깅과 중간 재개가 쉽다.

4-3. 프레임 처리 4스텝 — 파이프라인의 진짜 엔진

produce_assets 단계는 스토리보드의 각 프레임(장면)을 FrameProcessor에 하나씩 넘긴다. 한 프레임이 완성 영상 세그먼트가 되는 과정이 4스텝이다.

# services/frame_processor.py — TTS 길이를 영상 생성에 전달
if is_video_workflow and frame.duration:
    media_params["duration"] = frame.duration  # TTS 오디오에서 잰 길이

4-4. 왜 "static 템플릿"이 최적화인가

plan_visuals 단계에 영리한 분기가 있다. 템플릿 이름이 static_으로 시작하면(고정 배경 스타일) 이미지 생성 자체를 건너뛴다. 로그에 "Savings: N LLM calls + N media generations"가 찍힌다. 장면마다 그림이 꼭 필요한 건 아니라는 통찰 — 텍스트·타이포 중심 영상이면 이미지 생성 비용을 통째로 아낀다. 반대로 image_·video_ 템플릿이면 장면별 프롬프트를 LLM으로 배치 생성한다(batch=10, 실패 시 최대 3회 재시도, 개수 안 맞으면 재시도).

4-5. 후반 작업 — 세그먼트 합치기 + BGM

모든 프레임 세그먼트가 완성되면 post_production이 VideoService.concat_videos로 이어 붙이고 배경음악을 얹는다. BGM은 bgm_mode="loop"로 영상 길이에 맞춰 반복되고, 볼륨은 나레이션을 방해하지 않도록 0.2로 낮춘다. 기본 BGM 파일은 bgm/default.mp3. 마지막 finalize에서 태스크 메타데이터와 스토리보드를 저장하고 최종 결과 객체를 반환한다.

5디렉토리 구조 해부

6학습 포인트

6-1. 실제 코드 발췌

LLM 서비스 — Ollama를 위한 dummy key 트릭

# services/llm_service.py — OpenAI SDK 하나로 모든 provider
# Ollama는 API 키가 필요 없지만 SDK는 키를 요구한다 → 가짜 키를 넣는다
final_api_key = api_key or self._get_config_value("api_key") or "dummy-key"

견고한 LLM JSON 파싱 (utils/content_generators.py)

# LLM이 ```json ... ``` 코드블록으로 감싸 답해도, 앞뒤에 말을 붙여도 파싱
def _parse_json(text):
    # markdown 코드펜스 제거 + 정규식으로 { ... } 추출 후 json.loads
    ...  # 개수가 안 맞으면 호출부에서 max_retries=3으로 재시도

프레임 병렬 처리 (pipelines/standard.py)

# RunningHub(클라우드)면 프레임을 동시에, 아니면 순차로
if is_runninghub and runninghub_concurrent_limit > 1:
    semaphore = asyncio.Semaphore(runninghub_concurrent_limit)
    results = await asyncio.gather(*tasks)  # 프레임 병렬

나레이션 생성 프롬프트의 품질 규칙 (prompts/topic_narration.py)

# Role Definition: 콘텐츠 전문가 역할 부여
# - 단어 수 {min_words}~{max_words} 제한
# - 언어 일관성 강제: 입력이 영어면 출력도 영어
# - 오프닝 다양성: 같은 단어로 2회 이상 시작하면 실패
# - 출력은 엄격한 {"narrations": [...]} JSON

6-2. 이 저장소에서 배울 수 있는 기술

7시스템 요구사항

소스로 실행 (macOS / Linux)

# 전제조건: uv + ffmpeg 설치
git clone https://github.com/AIDC-AI/Pixelle-Video.git
cd Pixelle-Video
cp config.example.yaml config.yaml   # 설정 편집(LLM·모델·API 키)
uv run streamlit run web/app.py       # 의존성 자동 설치 후 실행
# → http://localhost:8501

Docker

docker-compose up -d
# init이 config.yaml 자동 생성, api(8000)·web(8501) 2컨테이너 기동
# 중국 미러가 필요하면: USE_CN_MIRROR=true

8직접 해볼 수 있는 실습 과제

9심화 학습 로드맵

10핵심 키워드 사전

11참고 링크