mockfeed 딥다이브
— FFmpeg 플래그 20개를 외울 필요 없이, 명령 한 줄로 '가짜 라이브 영상'을 만들어 RTMP·SRT·UDP로 쏘는 CLI

mockfeed/mockfeed. AWS MediaLive·MediaConnect 같은 클라우드 영상 서비스를 연동·테스트하려면 실제 라이브 스트림이 필요한데, mockfeed는 입력 영상 파일 없이 컬러바·테스트 패턴을 즉석 생성해 RTMP/SRT/UDP 엔드포인트로 송출하는 파이썬 명령줄 도구다. 정체는 잘 설계된 FFmpeg 래퍼로, "왜 B프레임을 꺼야 하나, 왜 GOP를 2초로 맞춰야 하나" 같은 서비스별 인코더 요구사항을 프리셋(preset)으로 박제해, 손으로 FFmpeg 명령 20줄을 쓰고 디버깅하던 일을 mockfeed push --preset aws-medialive-rtmp 한 줄로 줄인다. 진짜 가치는 코드가 아니라 "스트리밍 도메인 지식의 깔끔한 코드화" — pydantic으로 설정을 타입세이프하게 검증하고, 순수 함수로 FFmpeg 명령을 조립하며, 스레드로 실시간 진행률을 그린다. (저장소: mockfeed/mockfeed · 언어 Python 3.13+ · 본체 ~1,700줄 + 테스트 ~2,657줄 · v0.1.0 · 라이선스 MIT · 저자 Israjur Rahman · 외부 의존 FFmpeg 6.0+ — TrendShift 라이브 멘션, r/VIDEOENGINEERING 화제)

1프로젝트 한줄 요약

"입력 영상 없이 컬러바를 즉석으로 만들어, 클라우드 영상 서비스가 받아 줄 형식 그대로 라이브 송출한다."

README의 Before/After가 이 도구의 전부를 말해 줍니다 — 손으로 쓰던 FFmpeg 한 덩어리가 명령 한 줄로 줄어듭니다:

# Before: 손으로 쓰는 FFmpeg (외우기도 디버깅하기도 괴롭다)
ffmpeg -re -f lavfi -i smptebars=size=1920x1080:rate=30 \
  -f lavfi -i sine=frequency=1000:sample_rate=48000 \
  -map 0:v -map 1:a -c:v libx264 -preset veryfast -profile:v main \
  -b:v 5000k -maxrate 5000k -bufsize 10000k -g 60 -keyint_min 60 \
  -sc_threshold 0 -bf 0 -pix_fmt yuv420p \
  -c:a aac -profile:a aac_low -b:a 128k -ac 2 -ar 48000 \
  -f flv rtmp://your-medialive-endpoint/live/key

# After: mockfeed
mockfeed push --preset aws-medialive-rtmp --destination rtmp://your-endpoint/live/key

이 문서가 파고드는 건 사용법만이 아니라 그 안의 소프트웨어 설계입니다 — "프리셋이든 설정 파일이든 대화형이든 결국 하나의 검증 지점으로 모으는 법(pydantic 단일 진실원)", "FFmpeg 명령을 부수효과 없는 순수 함수로 만들어 테스트하는 법", "FFmpeg가 토해내는 진행 로그를 별도 스레드로 파싱해 실시간 대시보드를 그리는 법". 스트리밍 프로토콜과 깔끔한 CLI 설계를 한 레포에서 배우고 싶은 사람에게 좋은 소품입니다.

2왜 주목받는가

"영상 엔지니어라면 누구나 겪는 'FFmpeg 명령 지옥'을, 도메인 지식을 박제한 프리셋 CLI로 풀었다."

먼저, 푸는 문제 — 'FFmpeg는 강력하지만 외우기 괴롭다'

FFmpeg는 영상 처리의 만능 도구지만, 라이브 송출 명령은 플래그가 수십 개라 매번 다시 찾아보고, 틀리고, 디버깅하게 됩니다. 특히 클라우드 서비스마다 요구가 미묘하게 달라(RTMP는 FLV, SRT는 MPEG-TS, ABR엔 고정 GOP…), 한 번 맞춰 놓은 명령도 서비스가 바뀌면 무용지물입니다.

비결은 '코드가 아니라 도메인 지식이 자산'이라는 점

이 프로젝트가 영상 엔지니어 커뮤니티(r/VIDEOENGINEERING)에서 공감을 산 이유는 화려한 기능이 아니라 "우리가 매번 검색하던 그 지식을 깔끔히 정리해 줬다"는 데 있습니다.

3기술 스택 전체 지도

"파이썬 현대 도구 모음(uv·typer·pydantic·rich) + 시스템에 설치된 FFmpeg. 의존성 목록만 봐도 'CLI를 제대로 만들겠다'는 의도가 읽힌다."

mockfeed는 DB·네트워크 서버가 없는 순수 CLI 도구입니다. 핵심 의존성이 CLI·설정검증·터미널UI·FFmpeg 연동에 또렷이 몰려 있어, pyproject.toml이 곧 설계 의도입니다.

① 언어 · 패키징

② CLI · 설정 · UI 핵심 4종

③ FFmpeg를 코드로 안전하게 구동하는 법

mockfeed의 FFmpeg 연동에는 보안·안정성 디테일이 있습니다.

④ 개발 품질 도구 — "테스트가 본체보다 크다"

이 작은 프로젝트의 진짜 인상적인 부분입니다. 개발 도구로 pytest ≥8, ruff ≥0.9(린트+포맷), pyright(strict 타입체크)를 쓰고, 테스트 코드가 ~2,657줄로 본체(~1,700줄)보다 큽니다. 비결은 명령 빌더를 순수 함수로 만들어 FFmpeg 실행 없이 "인자 배열이 올바른가"만 단언하는 것 — 실제 ffmpeg가 필요한 테스트는 integration 마커로 분리해 평소엔 제외합니다.

4아키텍처 심화 분석 (설정 한 줄이 송출되기까지)

"입력 3종(프리셋·파일·대화형) → 단일 검증 지점(FeedConfig) → 순수 함수로 명령 조립 → 프로세스 감시 → 실시간 대시보드. 한 방향으로 흐른다."

전체 데이터 흐름 한 장

설계 ① — 단일 진실원(pydantic FeedConfig): 입력이 셋이어도 검증은 한 곳

가장 핵심적인 설계입니다. 프리셋이든 설정 파일이든 대화형이든, 모든 입력은 결국 하나의 FeedConfig 객체로 수렴합니다. 검증·명령생성은 그 뒤 한 군데서만 일어나므로, 입력 경로가 늘어나도 빌드 로직은 건드릴 필요가 없습니다.

# config/feed_config.py — 범위·허용값을 타입으로 강제
class VideoConfig(BaseModel):
    resolution: Literal["480p30","720p30","720p60","1080p30","1080p60"] = "1080p30"
    codec: Literal["h264","hevc"] = "h264"
    bitrate_kbps: int = Field(5000, ge=500, le=20000)   # 500~20000만 허용
    keyframe_interval_seconds: int = Field(2, ge=1, le=10)
    pattern: Literal["smptebars","testsrc2","mandelbrot","color"] = "smptebars"

class OutputConfig(BaseModel):
    protocol: Literal["rtmp","rtmps","srt","udp"]
    # protocol → container 자동 도출 (rtmp→flv, srt/udp→mpegts)

설계 ② — 명령 빌더와 실행기의 분리: 순수 함수 vs I/O

build_command()는 부수효과가 전혀 없는 순수 함수입니다 — FeedConfig를 받아 FFmpeg 인자 리스트를 돌려줄 뿐, 파일도 안 만들고 프로세스도 안 띄웁니다. 그래서 FFmpeg를 실행하지 않고도 "인자 배열이 올바른가"를 테스트할 수 있습니다. 실제 I/O·시그널은 FeedRunner가 따로 담당합니다.

# ffmpeg/command_builder.py (개념)
def build_command(config: FeedConfig) -> list[str]:
    w, h, fps = _RESOLUTION_SPECS[config.video.resolution]
    gop = fps * config.video.keyframe_interval_seconds      # GOP 자동 계산
    args = ["ffmpeg","-re","-f","lavfi","-i",
            f"{config.video.pattern}=size={w}x{h}:rate={fps}", ...]
    args += ["-b:v",f"{br}k","-maxrate",f"{br}k",
             "-bufsize",f"{br*2}k",                          # CBR + 버퍼 2배
             "-g",str(gop),"-keyint_min",str(gop),
             "-sc_threshold","0","-bf","0", ...]             # 씬컷·B프레임 끔
    return args   # 부수효과 0 → 테스트가 이 배열만 단언

설계 ③ — 스레드 기반 비차단 진행률

메인 스레드는 process.wait()로 FFmpeg 종료를 기다리고, 별도 데몬 스레드가 FFmpeg의 stderr를 한 줄씩 읽어 진행률을 파싱합니다. -progress pipe:2가 토해내는 key=value 블록을 상태머신으로 누적하다가, progress=continue|end를 만나면 한 이벤트로 묶어 콜백을 호출합니다. = 없는 일반 로그 줄은 무시하므로, 로그와 진행률이 섞여 와도 견고합니다.

설계 ④ — 프로토콜 → 컨테이너 자동 도출

사용자는 "RTMP로 보낼래"만 고르면 됩니다. 컨테이너(FLV/MPEG-TS)는 프로토콜에서 자동으로 정해집니다.

5디렉토리 구조 해부

"패키지 본체 14개 파일이 config / ffmpeg / output / presets로 깔끔히 갈린다. 가장 중요한 건 스키마·명령빌더·프리셋 YAML 세 곳."

가장 중요한 세 파일

config/feed_config.py(스키마) · ffmpeg/command_builder.py(명령 생성) · presets/*.yaml(박제된 지식)이 mockfeed의 삼각편대입니다. 스키마가 "무엇이 올바른 설정인가"를 정의하고, 빌더가 "그 설정을 FFmpeg 언어로 번역"하며, 프리셋이 "현업이 검증한 정답값"을 담습니다. 나머지(cli·interactive·runner·reporter)는 이 셋을 사용자와 잇는 배관입니다.

6학습 포인트 (기술별 — 배울 것 + 실습 아이디어)

"라이브 스트리밍 프로토콜·FFmpeg 안전 구동·pydantic 설계·CLI 설계·순수함수 테스트가 한 레포에 압축돼 있다."

① 라이브 스트리밍 프로토콜 실전 지식

배울 것: RTMP→FLV, SRT→MPEG-TS 매핑, SRT의 caller/listener 모델과 latency를 마이크로초로 주는 이유, ABR(적응형 비트레이트)을 위한 고정 GOP 정렬과 씬컷 키프레임 비활성화. 단순 개념이 아니라 "왜 클라우드 ingest가 거부하는가"라는 실패 중심.

실습: ffplay udp://127.0.0.1:5000를 띄워 두고 mockfeed로 UDP 송출 → 화면에 컬러바가 뜨는지 확인. 같은 영상을 RTMP로 바꿔 보내 컨테이너가 FLV로 바뀌는 걸 명령에서 확인.

② FFmpeg를 코드로 안전하게 구동

배울 것: shell=False + 인자 리스트로 셸 인젝션 차단, lavfi 가상 소스로 입력 파일 없이 신호 생성, -progress pipe:2로 머신리더블 진행률 받기, SIGTERM→SIGKILL 2단계 graceful shutdown.

실습: 파이썬 subprocess.Popen으로 FFmpeg를 띄우고 stderr를 별도 스레드로 읽어 진행률을 출력. Ctrl-C 시 SIGTERM을 보내고 5초 후 SIGKILL하는 종료 로직을 구현.

③ pydantic v2로 설정을 타입세이프하게

배울 것: Literal로 enum 강제, Field(ge=,le=)로 범위, @model_validator(mode="after")로 교차필드 검증(scheme↔protocol↔container 일관성), model_copy(update=)로 불변 병합. "잘못된 입력을 일찍, 친절하게 막는" 설계.

실습: pydantic으로 "비트레이트 500~20000, 코덱은 h264/hevc만" 같은 설정 모델을 만들고, 범위를 벗어난 값을 넣어 에러 메시지를 관찰. 두 필드의 일관성을 검사하는 validator를 추가.

④ 잘 설계된 CLI — Typer + 대화형 폴백

배울 것: Typer로 서브커맨드(push/validate/presets) 구성, 인자 없이 실행하면 questionary 대화형으로 폴백, 상호배타 옵션 처리, 의미 있는 exit code, rich 라이브 대시보드.

실습: Typer로 "인자를 주면 그대로 실행, 안 주면 화살표 메뉴로 묻는" 미니 CLI를 만들기. rich의 Live로 1초마다 갱신되는 진행 패널을 붙여 보기.

⑤ "순수 함수 + I/O 분리" 테스트 전략

배울 것: 핵심 로직(build_command)을 부수효과 없는 함수로 만들어 외부 도구 없이 단언, 실제 ffmpeg가 필요한 테스트는 integration 마커로 분리. 그 결과 테스트 코드가 본체보다 커진 품질 문화.

실습: 내 코드에서 "데이터 → 명령/쿼리 문자열"을 만드는 부분을 순수 함수로 떼어내, 외부 실행 없이 출력만 검증하는 단위 테스트를 작성. 무거운 통합 테스트엔 pytest 마커를 달기.

⑥ 도메인 지식의 코드화 + 보안 감각

배울 것: 프리셋 YAML 주석에 결정 근거 + 1차 출처(AWS 문서 URL)를 남기는 문서화 문화, IDEAS.md로 마찰점을 기록하는 도그푸딩, 그리고 URL scheme 화이트리스트·위험 IP 차단·sentinel 호스트 감지 같은 입력 검증 보안.

실습: 자주 쓰는 복잡한 명령(예: 백업·배포 스크립트)을 "근거 주석이 달린 프리셋"으로 정리해 보기. 사용자 입력 URL을 받을 때 scheme 화이트리스트로 거르는 검증기를 작성.

7시스템 요구사항 · 옵션

"무거운 인프라 0. 파이썬 3.13 + uv + 시스템 FFmpeg면 끝. GPU·DB·클라우드 계정도 (테스트만이면) 불필요."

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

"UDP 로컬 송출 → 맨손 FFmpeg와 비교 → 세 번째 프리셋 추가 → 미완성 오버레이 완성 → 미니 mockfeed 만들기."

9관련 기술 심화 학습 로드맵 (5주 플랜)

"FFmpeg 기초에서 출발해 라이브 프로토콜·pydantic·CLI 설계·테스트 전략까지, mockfeed를 길잡이 삼아."

10핵심 키워드 사전

"이 문서와 저장소에서 반복되는 스트리밍·FFmpeg·파이썬 용어를 한곳에 모았다."

11참고 링크

• GitHub 저장소 — github.com/mockfeed/mockfeed · 전체 레퍼런스 docs/USAGE.md
• TrendShift 라이브 멘션 — trendshift.io/repositories/62139
• AWS MediaLive RTMP_PUSH — planning-rtmp-push · 입력 사양 input-specification
• FFmpeg — ffmpeg.org · lavfi 필터 ffmpeg-filters · SRT Haivision/srt
• 도구 — uv · Typer · pydantic · rich