Music to Kinetic Typography

음악을 분석하여 자동으로 키네틱 타이포그래피 광고 영상을 생성하는 프로젝트

프로젝트 개요

두 가지 모드를 지원한다:

	Mode A: BGM (배경음악)	Mode B: Vocal (가사 음악)
입력 음악	보컬 없는 인스트루멘탈	가사가 포함된 음악
텍스트 소스	사용자가 직접 입력 (광고 카피)	음악에서 가사를 자동 추출
동기화 기준	드럼 온셋/비트에 맞춰 텍스트 배치	보컬 타이밍에 맞춰 가사 표시
주 용도	광고 카피 영상, 프로모션	뮤직비디오, 가사 영상
출력	가로형(1920x1080) + 세로형(1080x1920)	가로형(1920x1080)

---

Mode A: BGM (배경음악) 모드

사용자가 제공한 광고 카피를 배경음악의 드럼 비트에 맞춰 애니메이션으로 표현한다.

파이프라인

[BGM 파일] → [오디오 분석 + 드럼 온셋 감지] → [비트맵 생성] → [텍스트 배치] → [영상 렌더링] → [MP4 (가로+세로)]

처리 흐름

1. 오디오 분석 (audio/analyzer.py)

   • BPM 추출 및 비트 타이밍 검출 (librosa.beat.beat_track)
   • HPSS로 퍼커시브(드럼) 성분 분리 → 드럼 온셋 감지 (librosa.onset.onset_detect)
   • 음악 구간 분할 (intro / verse / chorus / outro) - RMS 에너지 기반
   • 비트별 에너지 강도 및 RMS 에너지 곡선 추출

2. 비트맵 생성 (audio/beat_map.py)

   • 드럼 온셋을 최우선 전환 포인트로 사용
   • 강한 드럼 히트(>0.5)에서 즉시 카피 전환
   • 1.5~4.0초 간격으로 텍스트 배치 (긴박한 리듬감)
   • 드럼 에너지 70% + 비트 에너지 30% 가중 결합
   • 에너지에 따라 scale/shake/bounce 등 강렬한 효과 자동 선택

3. 텍스트 배치

   • 사용자가 입력한 카피를 드럼 비트 구간에 자동 분배
   • 텍스트 role 지원: headline(1.3x), body(1.0x), brand(1.5x)
   • 카피가 부족하면 순환 반복하여 영상 전체를 채움

4. 영상 렌더링 (typography/renderer.py + video/composer.py)

   • 프레임별 타이포그래피 애니메이션 렌더링 (30fps)
   • 배경 + 텍스트 + 오디오 합성 → MP4 출력
   • 가로형(1920x1080) + 세로형(1080x1920) 동시 생성

---

Mode B: Vocal (가사 음악) 모드

가사가 포함된 음악에서 보컬과 가사를 추출하고, 보컬 타이밍에 맞춰 가사를 표시한다.

파이프라인

[음악 파일] → [보컬 분리] → [가사 추출 + 타이밍 정렬] → [타이포그래피 배치] → [영상 렌더링] → [MP4]
              ↘ [반주 분석 + 드럼 온셋 감지] ↗

처리 흐름

1. 보컬/반주 분리 (audio/separator.py)

   • demucs로 보컬 트랙과 반주 트랙을 분리 (--two-stems vocals)
   • 분리 결과 캐싱으로 재사용 지원
   • 서브프로세스로 실행하여 OpenMP 충돌 방지

2. 가사 추출 및 타이밍 정렬 (audio/lyrics_extractor.py)

   • Whisper 모델로 보컬에서 가사 텍스트 자동 추출 (word_timestamps=True)
   • 세그먼트 단위 시작/종료 시간 추출
   • 다국어 지원 (ko, en, ja 등)

3. 반주 분석 + 타이포그래피 배치

   • 반주 트랙에 대해 BGM과 동일한 오디오 분석 수행
   • 가사 타이밍에 맞춰 한 줄씩 표시
   • 드럼 온셋 근접 + 고에너지 구간에서 강렬한 효과 적용

4. 영상 렌더링

   • 원본 음악(분리 전) + 타이포그래피 영상 합성 → MP4 출력

---

타이포그래피 효과

두 모드에서 공유하는 애니메이션 효과:

효과	설명	적용 조건
Fade In/Out	빠른 등장/퇴장 (0.15초)	기본 전환, intro/outro
Scale	확대 펀치 후 수축 (최대 1.8x, ease-out-back)	에너지 > 0.5, chorus
Slide	방향 슬라이드 (에너지 비례 거리)	verse, 일반 전환
Bounce	위에서 내려찍히는 임팩트	에너지 > 0.7
Shake	강한 진동 + 스케일 펀치	에너지 > 0.7, 드럼 히트
Typewriter	한 글자씩 빠른 타이핑	intro, 내레이션 구간
Split	글자 분해/조합 (ease-out-expo)	전환 구간

이징 함수

• ease_out_cubic - 빠른 시작, 부드러운 정지
• ease_out_expo - 매우 빠른 시작, 순간 정지
• ease_out_back - 오버슈트 후 안정 (스케일 펀치용)
• ease_in_out_sine - 부드러운 가감속

---

기술 스택

영역	기술	용도
오디오 분석	librosa	BPM, 비트 검출, HPSS 드럼 분리, 온셋 감지
보컬 분리	demucs	보컬/반주 트랙 분리 (Mode B)
음성 인식	whisper	보컬에서 가사 추출 + 타이밍 (Mode B)
영상 생성	moviepy	비디오 클립 합성 및 렌더링
텍스트 렌더링	Pillow (PIL)	프레임별 텍스트 이미지 생성
수치 연산	numpy	오디오 데이터 및 애니메이션 계산
영상 인코딩	FFmpeg	최종 MP4 인코딩
CLI	argparse	커맨드라인 인터페이스

프로젝트 구조

musicToKneticTypography/
├── README.md
├── requirements.txt
├── main.py                     # CLI 진입점 (모드 분기)
├── config.py                   # 기본 설정값 (영상, 폰트, 애니메이션)
│
├── audio/
│   ├── analyzer.py             # 오디오 분석 (BPM, 비트, 드럼 온셋, 에너지)
│   ├── beat_map.py             # 드럼 온셋 기반 비트맵 생성
│   ├── separator.py            # 보컬/반주 분리 (Mode B)
│   └── lyrics_extractor.py     # 가사 추출 + 타이밍 정렬 (Mode B)
│
├── typography/
│   ├── effects.py              # 애니메이션 효과 (7종 + 이징 함수 4종)
│   ├── layout.py               # 텍스트 배치 및 레이아웃
│   └── renderer.py             # 프레임 단위 텍스트 렌더링
│
├── video/
│   ├── composer.py             # 영상 합성
│   └── exporter.py             # MP4 출력
│
├── modes/
│   ├── bgm_mode.py             # Mode A 파이프라인 (가로+세로 동시 생성)
│   └── vocal_mode.py           # Mode B 파이프라인
│
└── tests/

사용법

# 설치
pip install -r requirements.txt

# Mode A: BGM 모드 - 광고 카피를 배경음악에 맞춰 영상 생성
python main.py bgm --music bgm.mp3 \
  --text "새로운 시작" "당신의 하루를 더 특별하게" "BRAND"

# Mode A: 옵션 지정
python main.py bgm --music bgm.mp3 \
  --text "Hello" "World" \
  --duration 15 --fps 30 --output result.mp4

# Mode B: Vocal 모드 - 가사 자동 추출하여 영상 생성
python main.py vocal --music song.mp3

# Mode B: 가사를 직접 제공
python main.py vocal --music song.mp3 --lyrics lyrics.txt --language ko

CLI 옵션

BGM 모드

옵션	기본값	설명
--music	(필수)	배경음악 파일 경로
--text	(필수)	광고 카피 텍스트 (공백으로 구분)
--output	output_bgm.mp4	출력 파일 (자동으로 _landscape/_portrait 접미사 추가)
--duration	30.0	영상 길이 (초)
--fps	30	프레임 레이트
--font	시스템 폰트	폰트 파일 경로

Vocal 모드

옵션	기본값	설명
--music	(필수)	음악 파일 경로
--lyrics	자동 추출	가사 텍스트 파일
--language	ko	가사 언어 (ko, en, ja 등)
--output	output_vocal.mp4	출력 파일 경로
--fps	30	프레임 레이트
--font	시스템 폰트	폰트 파일 경로

---

개발 진행 상황

Phase 1 - 공통 기반 구축 ✅

• 프로젝트 환경 설정 (requirements.txt, 디렉토리 구조)
• CLI 진입점 및 모드 분기 로직 (main.py)
• 공통 오디오 분석 모듈 - BPM, 비트, 에너지 (audio/analyzer.py)
• 비트맵 데이터 구조 정의 (TextEvent dataclass)

Phase 2 - Mode A (BGM) 완성 ✅

• 사용자 텍스트 → 비트 구간 자동 분배 로직
• 기본 타이포그래피 렌더링 (Pillow)
• 애니메이션 효과 구현 (fade, scale, slide, bounce, shake, typewriter, split)
• 비트 동기화 + 영상 렌더링 → MP4 출력
• 가로형 + 세로형 동시 생성

Phase 3 - Mode B (Vocal) 완성 ✅

• 보컬/반주 분리 (demucs 연동, 캐싱 지원)
• 가사 추출 + 세그먼트 단위 타이밍 (whisper 연동)
• 가사 타이밍 → 타이포그래피 배치
• Mode B 엔드투엔드 파이프라인

Phase 4 - 드럼 비트 동기화 강화 ✅

• HPSS 기반 퍼커시브(드럼) 성분 분리 및 온셋 감지
• 드럼 온셋 기반 텍스트 전환 (1.5~4초 간격)
• 드럼 에너지 + 비트 에너지 가중 결합
• 에너지 기반 효과 자동 선택 (scale/shake/bounce 순환)
• 빠른 이징 함수 추가 (ease_out_expo, ease_out_back)
• 애니메이션 속도 2배 이상 향상 (페이드 0.15초, 스케일 펀치 0.1초)

Phase 5 - 고도화 (예정)

• 에너지 기반 동적 배경 효과
• 스타일 템플릿 시스템
• 간주 구간 장식 애니메이션 (Mode B)
• chorus 구간 핵심 카피 강조 배치
• 세로형 영상 Mode B 지원