PORTFOLIO CASE STUDY
Video Highlighter: 자동 하이라이트/쇼츠 추출 앱을 만들고, 실제 Windows 오류까지 패치한 과정
긴 영상 1개를 입력하면 20분 하이라이트 1개와 세로형 쇼츠 10개를 자동으로 생성하는 도구를 설계·구현했다. 이후 사용자가 요구한 "더블클릭만으로 설치되고 실행되는 앱" 경험까지 포함하도록 제품 형태를 확장했고, Windows 런처/경로 처리/CUDA DLL 오류를 실제 피드백 기반으로 연속 패치한 사례다.
"동영상을 주면 자동으로 하이라이트를 뽑아 20분짜리 영상과 쇼츠 10개를 뽑아주는 프로그램 만들어줘."
| 출발 요구사항 | 긴 영상 1개를 넣으면 20분짜리 하이라이트 1개와 세로형 쇼츠 10개를 자동으로 추출하는 프로그램. |
| 확장 요구사항 | 브라우저가 아니라 압축 해제 후 더블클릭만으로 설치·실행되는 데스크톱 앱 형태로 패키징. |
| 최종 상태 | CUDA DLL이 없는 환경에서는 CPU로 자동 폴백하도록 수정한 v4까지 배포. 실제 사용자 PC 최종 재확인은 별도 필요. |
1. 문제 정의
처음 요청은 단순해 보였다. 긴 영상을 넣으면 핵심 구간을 자동으로 뽑아 요약 영상과 쇼츠를 생성하는 프로그램을 원한다는 것이었다. 하지만 대화가 진행될수록 요구사항의 무게 중심은 "알고리즘"에서 "실제로 바로 실행되는 제품 경험"으로 이동했다.
- 긴 영상을 사람이 직접 훑지 않고도 핵심 구간을 빠르게 뽑아내고 싶었다.
- 결과물은 긴 형식의 요약 영상 1개와 짧은 쇼츠 여러 개로 동시에 활용 가능해야 했다.
- 처음엔 기능 구현이 핵심이었지만, 실제 사용 단계에선 설치와 실행 경험이 더 큰 병목이 됐다.
이 프로젝트의 핵심 해석
영상 편집 자동화 기능을 만드는 것만으로는 부족했다. 사용자가 압축을 풀고 더블클릭했을 때 실제로 켜지고, 실패하더라도 어디서 막혔는지 알 수 있게 만드는 것까지가 요구사항이었다.
2. 솔루션 구조와 파이프라인
구현은 빠른 MVP를 우선한 뒤, 이후 배포성과 안정성을 강화하는 방향으로 진행했다. 전사, 장면 검출, 점수화, 선택, 렌더링 단계를 모듈 단위로 분리해 UI나 포장 방식이 바뀌어도 코어 파이프라인은 재사용되도록 설계했다.
- 입력 분석 - ffprobe로 영상 메타데이터를 읽고 작업 가능 여부를 확인한다.
- 오디오 추출 - 전사 정확도를 위해 WAV 16k mono 오디오를 만든다.
- 전사 - faster-whisper와 VAD를 이용해 문장 및 word timestamp를 얻는다.
- 장면 검출 - PySceneDetect로 컷 전환 지점을 계산한다.
- 점수화·선택 - RMS, 말 밀도, 키워드 등 휴리스틱 신호를 합쳐 하이라이트 후보를 뽑는다.
- 렌더링 - 20분 하이라이트 1개, 세로 쇼츠 10개, JSON 메타데이터와 SRT를 출력한다.
| 구성 요소 | 역할 |
|---|---|
| faster-whisper | 음성 전사, word timestamp, VAD 기반 구간 분석 |
| PySceneDetect | 장면 전환 감지 |
| FFmpeg / ffprobe | 오디오 추출, 메타데이터 파악, 클립 렌더링 |
| Tkinter / Streamlit / CLI | 데스크톱 앱, 브라우저 UI, 스크립트 실행 인터페이스 제공 |
| imageio-ffmpeg | 데스크톱 버전에서 시스템 FFmpeg 의존성을 줄이기 위한 실행 경로 |
3. 버전별 개발 과정
개발은 한 번에 완성본을 내는 방식이 아니라, 사용자 피드백이 들어올 때마다 배포 단위를 다시 조정하는 식으로 진행됐다. 특히 기능 구현에서 끝나는 것이 아니라 설치/실행 경험을 제품의 일부로 다뤘다는 점이 중요하다.
| 버전 | 핵심 변화 | 주요 구현 내용 |
|---|---|---|
| v1 - MVP | 먼저 동작하는 자동 편집 파이프라인 확보 | CLI + Streamlit UI, faster-whisper 전사, PySceneDetect 장면 검출, 휴리스틱 점수화, 20분 하이라이트 + 쇼츠 10개 생성 |
| v2 - 데스크톱 앱 | 더블클릭 설치·실행 요구 반영 | Tkinter GUI, 멀티 OS 런처, 첫 실행 시 가상환경 생성 및 패키지 설치, imageio-ffmpeg 경로 추가, Windows 바로가기 생성 |
| v2.1 - Windows 런처 수정 | 배치 파일 줄바꿈 이슈 대응 | CRLF 재작성, PowerShell bootstrap 구조로 변경, bootstrap_windows.log 추가 |
| v3 - 경로 처리 강화 | GetFullPath 경로 인자 오류 대응 | 앱 루트를 인자로 넘기지 않고 스크립트 자기 위치 기준으로 계산, Python 3.10~3.13 우선 선택, 로그 강화 |
| v4 - CUDA 폴백 | GPU 전사 시 DLL 누락 중간 실패 대응 | CUDA 런타임 오류 감지 시 CPU(int8) 모드로 자동 전환하도록 transcriber 폴백 로직 추가 |
버전 전개의 의미
v1은 "돌아가는가"에 집중했고, v2 이후는 "사용자가 바로 켤 수 있는가", "실패해도 회복 가능한가"에 집중했다. 이 변화가 곧 프로토타입에서 제품형 구조로 이동한 지점이다.
4. 사용자 피드백 기반 디버깅
실사용 단계에서 나온 오류는 대부분 하이라이트 알고리즘이 아니라 배포와 실행 환경에서 발생했다. 아래 3건은 사용자가 올린 스크린샷만을 바탕으로 진단하고 패치까지 이어진 사례다.
Case 1. Windows 배치 런처 줄바꿈 문제
증상 - "BOOTSTRAP", "accept-package-agreements" 같은 문자열이 내부 명령처럼 실행되는 현상
원인 진단 - 초기 배포본의 .bat 파일이 Windows 친화적 CRLF가 아니라 LF 줄바꿈으로 저장되어, CMD에서 줄 경계가 깨진 것으로 판단
조치 - 배치 파일을 CRLF로 재작성하고 설치 로직을 PowerShell bootstrap으로 분리, 실패 시 bootstrap_windows.log를 남기도록 변경
결과 - 런처 패치 배포 완료
Case 2. GetFullPath 경로 인자 오류
증상 - PowerShell에서 "경로에 잘못된 문자가 있습니다" 예외 발생
원인 진단 - 배치 파일이 앱 폴더 경로를 인자로 넘길 때, 끝의 백슬래시와 따옴표 처리 때문에 GetFullPath()가 잘못된 문자열을 받는 버그
조치 - 앱 루트를 인자로 넘기지 않고 bootstrap 스크립트가 자기 위치 기준으로 경로를 계산하도록 구조 수정. Python 버전 선택과 로그도 강화
결과 - v3 반영 완료
Case 3. cublas64_12.dll 누락으로 GPU 전사 실패
증상 - 영상 처리 중간에 "Library cublas64_12.dll is not found or cannot be loaded" 팝업 발생
원인 진단 - faster-whisper의 CUDA 경로가 실행되었지만, 사용자 PC에 필요한 NVIDIA CUDA/cuBLAS/cuDNN 런타임이 완비되지 않은 상황으로 판단
즉시 대응 - device=cpu 사용을 안내
영구 대응 - transcriber가 CUDA 관련 DLL 오류를 감지하면 CPU(int8)로 자동 폴백하도록 수정해 v4 패치 배포
디버깅에서 얻은 교훈
배포형 소프트웨어의 초기 장애는 알고리즘보다 운영체제별 실행 습성, 줄바꿈, 인코딩, 경로 인자, 외부 런타임 같은 경계면에서 더 자주 발생한다. 그래서 기능만큼 중요한 설계 대상이 바로 실행 경험과 실패 대응성이다.
5. 산출물과 코드 구조
최종적으로 대화에서 만들어진 결과물은 단순한 코드 스니펫이 아니라, 실제로 실행 가능한 배포 단위와 문제별 패치 단위였다. 출력 구조와 모듈 구성을 보면, 후처리 및 기능 확장이 가능하도록 의식적으로 분리해 둔 흔적이 보인다.
생성 결과물 구조
output/
+- highlight_20min.mp4
+- transcript.json
+- scenes.json
+- moments.json
+- manifest.json
`- shorts/
+- short_01.mp4
+- short_01.srt
+- short_02.mp4
+- short_02.srt
`- ...영상 자산과 분석 메타데이터를 분리해 저장하므로, 이후 하이라이트 재선정이나 추천 로직 고도화, 외부 편집툴 연동 같은 방향으로 확장하기 쉽다.
핵심 모듈 구조
video_highlighter/
+- cli.py
+- desktop_app.py
+- pipeline.py
+- transcriber.py
+- scene_detection.py
+- audio_analysis.py
+- scoring.py
+- selection.py
+- render.py
+- ffmpeg_utils.py
+- models.py
`- config.py전사, 장면 검출, 점수화, 선택, 렌더링 단계를 분리해 두었기 때문에, CLI/Streamlit/Tkinter 어느 UI를 붙여도 코어 파이프라인은 그대로 재사용할 수 있다.
6. 포트폴리오에서 보여줄 수 있는 포인트
- 요구사항 구체화 - "영상 요약 도구"에서 시작했지만 실제로는 사용자가 더블클릭으로 실행할 수 있는 배포 UX까지 요구를 확장해 해석했다.
- 프로토타입-제품 전환 - MVP를 먼저 만든 뒤, 데스크톱 앱과 런처, 로그, 패치 배포 체계를 추가해 제품형 구조로 이동했다.
- 문제 해결 방식 - 스크린샷과 증상만으로 배치 파일, PowerShell 경로 처리, CUDA DLL 의존성이라는 서로 다른 계층의 문제를 분리해 다뤘다.
- 운영 안정성 - 실패 시 로그를 남기고, GPU 경로 실패 시 CPU로 자동 폴백하게 만들어 "죽지 않는" 실행 경험을 지향했다.
- 재사용 가능한 구조 - 전사-장면 검출-점수화-렌더링을 모듈화해 UI나 배포 형태가 바뀌어도 코어 파이프라인이 유지되게 설계했다.
- 실무형 커뮤니케이션 - 오류 원인을 단정하지 않고, 추정 근거와 우회책, 패치 방향을 함께 설명하는 방식으로 사용자 신뢰를 유지했다.
7. 현재 한계와 다음 단계
현재 버전은 실제로 동작하는 자동 편집 도구이지만, 편집 품질과 패키징 수준 측면에서는 더 올라갈 여지가 남아 있다. 특히 쇼츠 구도 품질, 의미 기반 랭킹, 완전한 단일 실행 파일화는 다음 단계의 핵심 과제다.
| 우선순위 | 제안 | 기대 효과 |
|---|---|---|
| 1 | 얼굴 추적·active speaker detection·자동 리프레이밍 추가 | 쇼츠 구도 품질 개선 |
| 2 | LLM/semantic ranking 기반 하이라이트 선택 보강 | 콘텐츠 맥락 반영력 향상 |
| 3 | 자동 자막 번인, 제목 생성, 썸네일 후보 생성 | 콘텐츠 제작 파이프라인 확장 |
| 4 | PyInstaller 등으로 진짜 단일 실행 파일 패키징 및 서명 | 설치 경험 단순화 |
| 5 | 런처 진단 정보 수집 및 오류 리포트 UX 개선 | 현장 장애 대응 시간 단축 |
8. 마무리
이 프로젝트는 자동 영상 편집 기능을 구현하는 데서 끝나지 않았다. 사용자가 실제로 실행 가능한 형태로 전달하고, 실행 중 발생한 Windows 런처, 경로 처리, GPU 의존성 문제를 패치 단위로 빠르게 수습한 과정까지 포함한다.
포트폴리오 관점에서 이 사례는 "기능 개발 + 배포 경험 + 현장 디버깅"을 하나의 작업 묶음으로 보여준다. 즉, 코드를 만드는 능력뿐 아니라, 사용자 환경에서 살아남는 제품 경험을 설계하고 개선한 사례로 설명할 수 있다.
한 줄 정리
이 작업은 단순한 자동 편집 스크립트 제작이 아니라, 실제 사용자 환경에서 실행되는 앱을 만들고 운영 이슈를 연속적으로 패치한 제품화 사례다.
가치 보강: 2026년 5월 23일 기준
이 글은 실제 업로드 흐름에 맞춰 2026년 5월 23일 기준으로 보강했습니다. 유튜브 관련 글은 제목 후보나 대본 예시만 있으면 얇게 보이기 쉬워서, 기획·제작·검수·업로드 후 확인까지 한 번에 이어지도록 보는 것이 좋습니다.
실전 적용 예시
| 상황 | 어떻게 보면 좋은가 |
|---|---|
| 기획 단계 | 시청자가 검색하거나 클릭할 이유를 한 문장으로 먼저 정합니다. |
| 제작 단계 | AI가 만든 제목, 대본, 설명란은 실제 영상 내용과 맞는지 반드시 다시 맞춥니다. |
| 업로드 전 | 썸네일 문구, 설명란 첫 두 줄, 고정댓글, 관련 링크가 서로 같은 메시지를 말하는지 확인합니다. |
읽고 바로 확인할 것
- 영상 내용과 제목이 과장 없이 일치하는가?
- 설명란 첫 문장만 읽어도 영상 주제가 보이는가?
- AI 합성 또는 변형 콘텐츠에 해당하면 YouTube 표시 기준을 확인했는가?
- 관련 글이나 후속 영상으로 이어지는 링크를 넣었는가?
'AI 활용 연구소' 카테고리의 다른 글
| ChatGPT·Gemini·Claude·Perplexity 차이 정리: 어떤 상황에 뭘 써야 할까? (0) | 2026.05.20 |
|---|---|
| AI 티 안 나게 글 다듬는 방법: 블로그·보고서 문체 체크리스트 (0) | 2026.05.20 |
| 정중한 업무 메일 작성기 무료 웹툴 사용법 (0) | 2026.04.24 |
| 회의록 요약기 무료 웹툴 사용법 (0) | 2026.04.24 |
| 자기소개서 이력서 개선기 무료 웹툴 사용법 (0) | 2026.04.24 |