TokyoAJ

도쿄아재

SVELTE 2025.06.30

SvelteKit과 Vimeo API를 이용한 동영상 업로드 시스템 구현

웹 애플리케이션에서 동영상을 업로드하고 관리하는 것은 복잡한 작업입니다. 이번 포스트에서는 SvelteKit과 Vimeo API를 활용하여 안전하고 효율적인 동영상 업로드 시스템을 구현하는 방법을 상세히 알아보겠습니다

.

프로젝트 개요

개발 목표

  1. Vimeo API를 통한 동영상 업로드 자동화
  2. TUS 프로토콜을 이용한 안정적인 파일 전송
  3. 비공개 설정으로 보안 강화
  4. 사용자 친화적인 업로드 인터페이스
  5. 업로드 상태 및 결과 정보 제공

기술 스택

  1. 프레임워크: SvelteKit
  2. API: Vimeo API v3.4
  3. 프로토콜: TUS (Tus Resumable Uploads)
  4. 언어: JavaScript (Node.js)
  5. 인증: Bearer Token


시스템 아키텍처

동영상 업로드 시스템은 다음 3단계로 구성됩니다:

  1. 비디오 메타데이터 생성: Vimeo에서 업로드용 비디오 객체 생성
  2. 파일 업로드: TUS 프로토콜을 통한 실제 파일 전송
  3. 정보 조회: 업로드된 비디오의 상세 정보 반환


핵심 구현 코드

API 엔드포인트 구조

export async function POST({ request }) {
try {
// FormData에서 비디오 파일 추출
const formData = await request.formData();
const videoFile = formData.get('video');
// 파일 검증
if (!videoFile) {
return json({ error: 'No video file provided' }, { status: 400 });
}
// 3단계 업로드 프로세스 실행
// ...
} catch (error) {
console.error('Upload error:', error);
return json({ error: 'Internal server error' }, { status: 500 });
}
}


1단계: 비디오 메타데이터 생성

const createResponse = await fetch('<https://api.vimeo.com/me/videos>', {
method: 'POST',
headers: {
'Authorization': `bearer ${VIMEO_ACCESS_TOKEN}`,
'Content-Type': 'application/json',
'Accept': 'application/vnd.vimeo.*+json;version=3.4'
},
body: JSON.stringify({
name: [videoFile.name](<http://videoFile.name>) || 'Uploaded Video',
description: 'Video uploaded via web interface',
privacy: {
view: 'nobody' // 비공개 설정
},
upload: {
approach: 'tus', // TUS 프로토콜 사용
size: videoFile.size
}
})
});

핵심 포인트:

  1. privacy.view: 'nobody': Basic 계정에서 비공개 업로드
  2. approach: 'tus': 안정적인 업로드를 위한 TUS 프로토콜 선택
  3. 파일 크기 사전 전달로 업로드 준비


2단계: TUS 프로토콜 파일 업로드

// 파일을 바이너리 버퍼로 변환
const videoBuffer = await videoFile.arrayBuffer();

// TUS PATCH 요청으로 파일 업로드
const uploadResponse = await fetch(uploadLink, {
method: 'PATCH',
headers: {
'Tus-Resumable': '1.0.0',
'Upload-Offset': '0',
'Content-Type': 'application/offset+octet-stream'
},
body: videoBuffer
});

TUS 프로토콜의 장점:

  1. 중단된 업로드 재개 가능
  2. 네트워크 불안정 상황에서도 안정적
  3. 대용량 파일 업로드에 최적화


3단계: 업로드 결과 조회

const videoResponse = await fetch(`https://api.vimeo.com${videoUri}`, {
headers: {
'Authorization': `bearer ${VIMEO_ACCESS_TOKEN}`,
'Accept': 'application/vnd.vimeo.*+json;version=3.4'
}
});

const videoData = await videoResponse.json();

// 클라이언트에 결과 반환
return json({
success: true,
video: {
uri: videoData.uri,
link: [videoData.link](<http://videoData.link>),
player_embed_url: videoData.player_embed_url,
name: [videoData.name](<http://videoData.name>),
status: videoData.status,
privacy: videoData.privacy.view
}
});


보안 및 베스트 프랙티스

1. 환경변수를 통한 토큰 관리

const VIMEO_ACCESS_TOKEN = process.env.VIMEO_ACCESS_TOKEN || 'fallback_token';

주의사항:

  1. 실제 운영환경에서는 환경변수 필수 사용
  2. Access Token은 절대 클라이언트 사이드에 노출 금지
  3. 적절한 스코프(scope) 권한만 부여


2. 에러 처리 전략

try {
// API 호출
} catch (error) {
console.error('Upload error:', error);
return json({ error: 'Internal server error' }, { status: 500 });
}

핵심 원칙:

  1. 구체적인 에러 정보는 서버 로그에만 기록
  2. 클라이언트에는 일반적인 에러 메시지만 전달
  3. 각 단계별 실패 시나리오 대비


3. 파일 검증

if (!videoFile) {
return json({ error: 'No video file provided' }, { status: 400 });
}

// 추가 검증 예시
if (videoFile.size > MAX_FILE_SIZE) {
return json({ error: 'File too large' }, { status: 413 });
}


프론트엔드 연동

업로드 요청

async function uploadVideo() {
const formData = new FormData();
formData.append('video', videoFile);
const response = await fetch('/api/upload', {
method: 'POST',
body: formData
});
const result = await response.json();
if (result.success) {
// 성공 처리
console.log('업로드 완료:', [result.video](<http://result.video>));
} else {
// 에러 처리
console.error('업로드 실패:', result.error);
}
}


성능 최적화 팁

1. 파일 크기 사전 확인

  1. 클라이언트에서 파일 크기 검증
  2. 적절한 파일 형식 필터링
  3. 업로드 전 사용자에게 예상 시간 안내

2. 진행률 표시

  1. TUS 프로토콜의 진행률 추적 활용
  2. 사용자 경험 향상을 위한 실시간 피드백

3. 에러 복구

  1. 네트워크 오류 시 자동 재시도 로직
  2. TUS의 resumable 기능 활용


확장 가능성

현재 구현을 기반으로 다음과 같은 기능을 추가할 수 있습니다:

  1. 배치 업로드: 여러 파일 동시 업로드
  2. 진행률 추적: WebSocket을 통한 실시간 상태 업데이트
  3. 썸네일 생성: 업로드 완료 후 자동 썸네일 추출
  4. 메타데이터 편집: 제목, 설명, 태그 등 편집 기능
  5. 권한 관리: 사용자별 업로드 권한 제어


마무리

이번 프로젝트를 통해 다음과 같은 핵심 개념들을 다뤘습니다:

  1. API 설계: RESTful한 업로드 엔드포인트 구현
  2. 프로토콜 이해: TUS를 통한 안정적인 파일 전송
  3. 보안 고려: Access Token 관리와 에러 처리
  4. 사용자 경험: 직관적인 업로드 인터페이스


Vimeo API와 TUS 프로토콜의 조합은 안정적이고 확장 가능한 동영상 업로드 시스템을 구축하는 데 매우 효과적입니다. 특히 웹 애플리케이션에서 동영상 콘텐츠를 다루는 개발자들에게 유용한 참고 자료가 될 것입니다.

다음 포스트에서는 업로드된 동영상의 메타데이터 편집과 재생 플레이어 커스터마이징에 대해 다뤄보겠습니다!


업로드 완료


댓글