CI 비디오 파이프라인용 다이어그램 슬라이드를 구축하며 배운 점
최근 자동화된 YouTube 비디오 파이프라인에 다이어그램과 차트를 추가했습니다.
핵심 요점은 간단합니다. 모든 것을 먼저 PNG 파일로 사전 렌더링하는 것입니다.
비디오 엔진 내부나 ffmpeg를 통해 시각 자료를 생성하려고 하지 마세요. 대신 공유된 PNG 핸드오프(handoff) 방식을 사용하세요. 이렇게 하면 파이프라인의 모든 부분을 테스트할 수 있고 교체하기도 쉬워집니다.
제가 어떻게 구축했는지, 그리고 무엇을 배웠는지 소개합니다.
아키텍처
제 파이프라인은 두 개의 호스트를 사용하는 시스템입니다. 한 호스트는 시각 자료와 오디오를 처리하고, 다른 호스트는 ffmpeg를 사용하여 모든 것을 하나의 비디오로 결합합니다.
ffmpeg는 JavaScript를 실행하거나 브라우저를 호출할 수 없기 때문에, 서로 다른 도구 간의 간극을 해결해야 했습니다.
• Mermaid(플로우차트용)는 Puppeteer와 Chromium을 통해 실행됩니다. • Matplotlib(차트용)은 Python을 통해 실행됩니다. • Pillow(슬라이드용)는 이미지 위에 직접 그립니다.
이러한 도구들은 서로 직접 통신할 수 없기 때문에, 저는 하나의 패턴을 사용합니다. PNG로 렌더링한 다음, 그 PNG를 Pillow 캔버스에 붙여넣는 방식입니다. 두 개의 코드 경로를 만드는 것보다 하나의 경로를 사용하는 것이 더 낫습니다.
주요 기술적 교훈
1. Chromium 설정
GitHub Actions에서 실행할 때 특정 플래그를 사용하지 않으면 Chromium이 실패합니다. 반드시 --no-sandbox와 --disable-setuid-sandbox를 포함해야 합니다. 이 플래그가 없으면 컨테이너가 프로세스를 차단합니다.
2. Mermaid 테마 설정
커스텀 색상을 사용하고 싶다면 내장된 dark 또는 forest 테마를 사용하지 마세요. 해당 테마들은 사용자의 설정을 덮어씁니다. "base" 테마를 사용하세요. 이것이 커스텀 팔레트가 안정적으로 작동하도록 보장하는 유일한 방법입니다.
3. Matplotlib 배경색
차트 배경을 슬라이드 배경과 일치시키는 것은 까다롭습니다. 다음 세 가지를 수행해야 합니다.
pyplot을 임포트하기 전에matplotlib.use("Agg")를 호출합니다.figure와axes모두에facecolor를 설정합니다.- 흰색 테두리를 제거하려면 파일을 저장할 때
bbox_inches="tight"를 사용합니다.
4. 신뢰성 및 페일세이프(Failsafes)
다이어그램 하나가 누락되었다고 해서 비디오 빌드 전체가 중단되어서는 안 됩니다. 저는 에러를 잡아내는 스캐폴드(scaffold)를 구축했습니다. 렌더링에 실패하면 파이프라인은 단순히 "visual unavailable" 플레이스홀더를 보여줍니다. 비디오는 그대로 완성됩니다. 이를 통해 일부 부분이 실패하더라도 콘텐츠를 검토할 수 있습니다.
트레이드오프(Trade-off)
사전 렌더링은 시간을 추가로 소요합니다. 각 Mermaid 다이어그램을 렌더링하는 데 약 2~4초가 걸립니다. 20개의 세그먼트로 구성된 비디오의 경우, 전체 빌드 시간에 약 20초가 추가됩니다. 제 요구 사항에서는 안정적인 시스템을 위해 충분히 감수할 만한 트레이드오프입니다.