독립형 미디어 분석 및 변환 도구 - YTConvert v0.1.0 (Initial MVP)
개인 또는 조직이 직접 관리하는, MP4, WebM, MP3 등 다양한 영상·음원 형식으로 변환할 수 있는 FastAPI, yt-dlp, FFmpeg 기반의 셀프 호스팅
**YTConvert(YouTube Convert)**는 개인 또는 조직이 직접 관리하는 서버 환경에 설치하여 사용하는 셀프 호스팅(Self-hosted) 미디어 분석 및 변환 소프트웨어입니다.
외부 이용자를 대상으로 영상 다운로드나 변환 서비스를 제공하는 공개 플랫폼이 아니라, 각 사용자가 자신의 독립적인 실행 환경에서 미디어 정보를 분석하고 필요한 형식으로 처리할 수 있도록 개발한 프로젝트입니다.
Python 기반 FastAPI와 yt-dlp, FFmpeg를 활용하며, 별도의 데이터베이스나 Redis 없이도 기본적인 미디어 분석과 작업 관리 기능을 구현할 수 있도록 구성했습니다.
개인적인 개발 및 운영 환경에서 필요한 기능을 구현하면서 시작했으며, 소프트웨어 구조를 참고하거나 자체 환경에 맞게 확장하려는 개발자를 위해 첫 공개 버전인 v0.1.0의 소스 코드를 GitHub에 공개했습니다.
GitHub에 공개된 것은 독립 설치형 소프트웨어의 소스 코드이며, 누구나 이용할 수 있는 공개 미디어 변환 서비스를 제공한다는 의미는 아닙니다.
1. 프로젝트의 목적과 운영 방식
YTConvert는 중앙에서 운영되는 온라인 변환 플랫폼이 아닌, 개별 설치 환경을 전제로 설계되었습니다.
소프트웨어를 설치한 사용자가 자신의 서버에서 실행하고, 접근 권한과 미디어 처리 범위를 직접 관리하는 방식입니다.
프로젝트의 기본 방향은 다음과 같습니다.
- 개인 또는 조직이 관리하는 독립 서버에 설치
- 중앙 서비스나 공용 변환 서버에 대한 의존성 최소화
- 서버 운영자가 접근 권한과 실행 정책을 직접 설정
- 허가된 미디어에 대한 분석 및 형식 변환 지원
- 소스 코드 검토, 자체 수정 및 기능 확장이 가능한 구조
- 불특정 다수를 대상으로 하는 공개 변환 서비스 운영을 기본 사용 모델에서 제외
YTConvert는 영상 콘텐츠를 자체적으로 제공하거나 배포하는 플랫폼이 아닙니다. 미디어의 소유권, 이용 권한 및 처리 목적은 개별 사용 환경에서 확인하고 관리해야 합니다.
2. 주요 기능
미디어 정보 분석
사용자가 입력한 YouTube URL을 yt-dlp로 분석하여 메타데이터와 이용 가능한 미디어 형식을 확인합니다.
주요 기능은 다음과 같습니다.
- 일반 YouTube URL 및 단축 URL 분석
- YouTube Shorts 및 라이브 영상 URL 분석 지원
- 영상 제목, 재생 시간 등 메타데이터 확인
- 해상도, 코덱, 비트레이트 및 스트림 정보 확인
- 영상과 음원 스트림 구분
- 분석 결과 캐싱을 통한 중복 요청 감소
메타데이터 분석 단계에서는 실제 미디어 파일을 다운로드하지 않습니다.
이 기능은 미디어의 기술적 특성을 확인하기 위한 것이며, 분석이 가능하다는 사실이 해당 콘텐츠의 다운로드 또는 변환 권한을 의미하지는 않습니다.
미디어 형식 변환
YTConvert는 서버에 설치된 FFmpeg를 이용하여 허가된 미디어를 필요한 출력 형식으로 처리할 수 있습니다.
| 구분 | 지원 형식 |
|---|---|
| 동영상 | MP4, WebM |
| 오디오 | MP3, M4A, Opus |
실제 이용 가능한 출력 형식은 원본 미디어의 특성과 서버에 설치된 FFmpeg 인코더에 따라 달라집니다.
원본이 제공하는 해상도를 기준으로 출력 옵션을 구성하며, 지원되지 않는 인코딩 형식은 선택할 수 없도록 처리합니다.
변환 기능은 기본적으로 비활성화되어 있으며, 서버 운영자가 실행 조건과 접근 정책을 확인한 후 명시적으로 활성화해야 합니다.
독립적인 작업 처리
미디어 변환은 웹 요청과 분리된 작업 프로세스에서 수행됩니다.
- 작업 생성 및 상태 조회
- SSE 기반 실시간 진행률 확인
- 작업 취소
- 처리 결과 파일 다운로드
- 작업별 JSON 상태 기록
- 오류 진단 및 실패 상태 관리
- 작업 시간과 시스템 자원 사용 제한
작업에는 고유한 식별자가 부여되며, 세션 기반 접근 제어를 통해 다른 사용자의 작업에 임의로 접근하지 못하도록 구성했습니다.
작업 기록은 별도의 데이터베이스 대신 로컬 JSON 파일로 관리합니다.
3. 기술 구성
YTConvert는 개인 서버에서 비교적 단순하게 구성하고 유지보수할 수 있도록 개발했습니다.
| 구성 요소 | 역할 |
|---|---|
| Python / FastAPI | 애플리케이션 및 REST API |
| Uvicorn | ASGI 서버 |
| yt-dlp | 미디어 메타데이터 및 스트림 정보 처리 |
| FFmpeg / ffprobe | 미디어 검사 및 형식 변환 |
| JavaScript / HTML / CSS | 웹 사용자 인터페이스 |
| JSON 파일 | 작업 상태 및 기록 관리 |
| Nginx | 선택적인 HTTPS 리버스 프록시 |
데이터베이스와 Redis를 필수 구성 요소로 요구하지 않으며, 중앙 인증 서비스나 외부 변환 서버를 전제로 하지 않습니다.
웹 인터페이스와 REST API를 함께 제공하지만, 이는 독립 설치 환경에서의 관리 및 기능 연동을 위한 것입니다.
API가 제공된다는 사실이 공개적인 미디어 변환 서비스 운영을 권장한다는 의미는 아닙니다.
4. 접근 제어와 기본 보안 정책
YTConvert는 외부 미디어를 취급하는 소프트웨어의 특성을 고려하여 여러 보안 및 실행 제한 기능을 포함합니다.
- 허용된 URL 및 호스트 검증
- 요청 횟수와 동시 처리 작업 제한
- 세션 기반 작업 접근 제어
- CSP 등 HTTP 보안 헤더 적용
- 작업 실행 시간 및 시스템 자원 제한
- 변환 프로세스의 실행 조건 확인
- 운영자가 설정한 네트워크 및 IP 접근 정책
특히 미디어 변환은 운영자가 허용한 환경에서만 실행하도록 구성할 수 있습니다.
프로젝트 개발자가 운영하는 테스트 환경 역시 불특정 다수에게 변환 기능을 제공하는 공개 서비스가 아니며, 승인된 호스트 및 네트워크에서의 제한적인 기능 검증을 목적으로 합니다.
보안상 주의사항
현재 버전은 외부 네트워크를 완전히 격리하는 기능을 제공하지 않습니다.
애플리케이션 수준의 URL 및 호스트 검증만으로 SSRF, DNS 재바인딩 등의 위험을 완전히 제거할 수는 없습니다.
따라서 외부에서 접근할 수 있는 환경에 설치하는 경우, 운영자는 별도의 네트워크 접근 통제, 실행 권한 제한, 방화벽 정책 등 필요한 보호 조치를 검토해야 합니다.
기본 보안 기능이 포함되어 있다는 사실이 모든 운영 환경의 안전성을 보장하지는 않습니다.
5. 저작권 및 이용 권한에 관한 안내
YTConvert는 사용자가 적법한 권한을 보유한 미디어를 분석하고 처리하기 위한 범용 소프트웨어입니다.
프로젝트는 타인의 저작물을 무단으로 복제하거나 배포하는 행위, 기술적 보호 조치를 무단으로 우회하는 행위 또는 제3자 서비스의 이용 조건을 위반하는 행위를 목적으로 개발되지 않았습니다.
소프트웨어를 이용할 때에는 다음 사항을 확인해야 합니다.
- 대상 미디어에 대한 다운로드, 복제 또는 변환 권한
- 해당 콘텐츠에 적용되는 저작권 및 라이선스 조건
- 관련 플랫폼의 이용약관과 기술적 이용 제한
- 처리 결과물의 보관, 공유 및 배포에 적용되는 법적 조건
영상의 기술적 분석이나 변환이 가능하다는 사실만으로 해당 행위가 법적으로 허용되는 것은 아닙니다.
YTConvert는 콘텐츠에 대한 이용 권한을 부여하지 않으며, 특정 콘텐츠의 다운로드나 변환이 적법하다고 보증하지 않습니다.
6. 소프트웨어 배포와 개별 운영의 구분
YTConvert의 GitHub 저장소는 소프트웨어 소스 코드와 기술 문서를 공개하기 위한 공간입니다.
프로젝트의 소스 코드 공개는 다음을 의미하지 않습니다.
- 누구나 접속할 수 있는 공용 다운로드 서비스 제공
- 개발자가 제3자의 미디어 변환 작업을 대신 수행
- 외부 콘텐츠의 이용 권한이나 라이선스 제공
- 모든 설치 환경에서의 보안 및 법적 적합성 보증
각 설치 환경은 해당 운영자가 직접 구성하고 관리합니다.
서버의 공개 여부, 접근 권한, 처리 대상 미디어, 데이터 보관 및 보안 정책은 각 운영 환경의 목적과 적용 법령에 따라 결정해야 합니다.
이러한 구분은 소프트웨어의 제공 범위와 실제 운영 책임을 명확히 설명하기 위한 것이며, 개발자나 운영자의 법적 책임을 일률적으로 면제한다는 의미는 아닙니다.
7. 첫 공개 버전 v0.1.0
이번 v0.1.0은 YTConvert의 첫 번째 공개 릴리스입니다.
미디어 정보 분석, 지원 형식 확인, 변환 작업 관리 및 결과 파일 처리까지 기본적인 기능을 구현한 초기 개발 버전입니다.
완성된 상용 서비스나 대규모 공개 플랫폼보다는 개인 서버 환경에서 기능을 검토하고, 자체 목적에 맞게 수정하거나 확장할 수 있는 독립형 개발 프로젝트에 가깝습니다.
향후 기능 개선과 구조 변경이 이루어질 수 있으며, 실제 운영 환경에 적용하기 전에는 관련 문서와 보안 설정을 충분히 확인하시기 바랍니다.
8. GitHub 및 소스 코드
설치 및 실행 방법, API 구성, 보안 정책과 배포 관련 내용은 GitHub 저장소의 README 및 docs/ 문서를 참고하시기 바랍니다.
YTConvert는 공개 미디어 변환 플랫폼이 아닌, 개별 운영자가 자신의 환경에서 직접 설치하고 관리하는 셀프 호스팅 소프트웨어입니다.
소스 코드는 개발 및 기술적 참고를 위해 공개하며, 실제 미디어 처리에는 적법한 이용 권한과 각 운영 환경에 필요한 보안 조치가 전제되어야 합니다.
이 개발자의 다른 프로젝트
