시작하기

1. 패키지 설치

   npm

   npm i @capgo/capacitor-youtube-player

   pnpm

   pnpm add @capgo/capacitor-youtube-player

   yarn

   yarn add @capgo/capacitor-youtube-player

   bun

   bun add @capgo/capacitor-youtube-player

2. 네이티브 프로젝트와 동기화

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

기본 사용법

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

// Initialize the player
const result = await YoutubePlayer.initialize({
  playerId: 'youtube-player',
  playerSize: { width: 640, height: 360 },
  videoId: 'dQw4w9WgXcQ',
  fullscreen: false,
  playerVars: {
    autoplay: 1,
    controls: 1
  }
});

// Play video
await YoutubePlayer.playVideo(result.player);

// Pause video
await YoutubePlayer.pauseVideo(result.player);

// Listen to player events
YoutubePlayer.addEventListener(result.player, 'onStateChange', (event) => {
  console.log('Player state:', event.data);
});

API 참조

initialize(options)

YouTube 플레이어 인스턴스를 초기화합니다.

const { player, playerReady } = await YoutubePlayer.initialize({
  playerId: 'my-player',
  playerSize: { width: 1280, height: 720 },
  videoId: 'VIDEO_ID',
  fullscreen: false,
  playerVars: {
    autoplay: 0,
    controls: 1,
    rel: 0
  }
});

비디오 제어 메서드

// Play
await YoutubePlayer.playVideo(playerId);

// Pause
await YoutubePlayer.pauseVideo(playerId);

// Stop
await YoutubePlayer.stopVideo(playerId);

// Seek to time
await YoutubePlayer.seekTo(playerId, seconds, allowSeekAhead);

// Load video by ID
await YoutubePlayer.loadVideoById(playerId, { videoId: 'VIDEO_ID' });

// Cue video (load without playing)
await YoutubePlayer.cueVideoById(playerId, { videoId: 'VIDEO_ID' });

재생목록 제어

// Load playlist
await YoutubePlayer.loadPlaylist(playerId, {
  listType: 'playlist',
  list: 'PLAYLIST_ID'
});

// Cue playlist
await YoutubePlayer.cuePlaylist(playerId, {
  playlist: ['VIDEO_ID_1', 'VIDEO_ID_2'],
  index: 0
});

// Navigate playlist
await YoutubePlayer.nextVideo(playerId);
await YoutubePlayer.previousVideo(playerId);
await YoutubePlayer.playVideoAt(playerId, index);

오디오 제어

// Mute/Unmute
await YoutubePlayer.mute(playerId);
await YoutubePlayer.unMute(playerId);

const { result } = await YoutubePlayer.isMuted(playerId);
console.log('Muted:', result.value);

// Volume (0-100)
await YoutubePlayer.setVolume(playerId, 50);
const { result } = await YoutubePlayer.getVolume(playerId);

재생 제어

// Playback rate
await YoutubePlayer.setPlaybackRate(playerId, 1.5);
const { result } = await YoutubePlayer.getPlaybackRate(playerId);

// Available rates
const { result } = await YoutubePlayer.getAvailablePlaybackRates(playerId);
console.log('Available rates:', result.value);

// Loop and shuffle
await YoutubePlayer.setLoop(playerId, true);
await YoutubePlayer.setShuffle(playerId, true);

품질 제어

// Set quality
await YoutubePlayer.setPlaybackQuality(playerId, 'hd720');

// Get current quality
const { result } = await YoutubePlayer.getPlaybackQuality(playerId);

// Get available qualities
const { result } = await YoutubePlayer.getAvailableQualityLevels(playerId);

플레이어 정보

// Duration
const { result } = await YoutubePlayer.getDuration(playerId);

// Current time
const { result } = await YoutubePlayer.getCurrentTime(playerId);

// Loaded fraction
const { result } = await YoutubePlayer.getVideoLoadedFraction(playerId);

// Player state
const { result } = await YoutubePlayer.getPlayerState(playerId);

// Video URL
const { result } = await YoutubePlayer.getVideoUrl(playerId);

이벤트 리스너

// State change
YoutubePlayer.addEventListener(playerId, 'onStateChange', (event) => {
  console.log('State:', event.data); // -1, 0, 1, 2, 3, 5
});

// Ready
YoutubePlayer.addEventListener(playerId, 'onReady', (event) => {
  console.log('Player ready');
});

// Error
YoutubePlayer.addEventListener(playerId, 'onError', (event) => {
  console.error('Player error:', event.data);
});

// Quality change
YoutubePlayer.addEventListener(playerId, 'onPlaybackQualityChange', (event) => {
  console.log('Quality:', event.data);
});

// Rate change
YoutubePlayer.addEventListener(playerId, 'onPlaybackRateChange', (event) => {
  console.log('Rate:', event.data);
});

// Remove listener
YoutubePlayer.removeEventListener(playerId, 'onStateChange', callback);

완전한 예제

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

export class YouTubeService {
  private playerId: string | null = null;

  async initPlayer(videoId: string) {
    try {
      const { player, playerReady } = await YoutubePlayer.initialize({
        playerId: 'main-player',
        playerSize: { width: 1280, height: 720 },
        videoId,
        fullscreen: false,
        playerVars: {
          autoplay: 0,
          controls: 1,
          modestbranding: 1,
          rel: 0
        }
      });

      this.playerId = player;

      // Set up event listeners
      YoutubePlayer.addEventListener(player, 'onReady', () => {
        console.log('Player is ready');
      });

      YoutubePlayer.addEventListener(player, 'onStateChange', (event) => {
        this.handleStateChange(event.data);
      });

      YoutubePlayer.addEventListener(player, 'onError', (event) => {
        console.error('YouTube error:', event.data);
      });

      return player;
    } catch (error) {
      console.error('Failed to initialize player:', error);
      throw error;
    }
  }

  private handleStateChange(state: number) {
    switch (state) {
      case -1:
        console.log('Unstarted');
        break;
      case 0:
        console.log('Ended');
        break;
      case 1:
        console.log('Playing');
        break;
      case 2:
        console.log('Paused');
        break;
      case 3:
        console.log('Buffering');
        break;
      case 5:
        console.log('Video cued');
        break;
    }
  }

  async play() {
    if (!this.playerId) return;
    await YoutubePlayer.playVideo(this.playerId);
  }

  async pause() {
    if (!this.playerId) return;
    await YoutubePlayer.pauseVideo(this.playerId);
  }

  async loadVideo(videoId: string) {
    if (!this.playerId) return;
    await YoutubePlayer.loadVideoById(this.playerId, { videoId });
  }

  async destroy() {
    if (!this.playerId) return;
    await YoutubePlayer.destroy(this.playerId);
    this.playerId = null;
  }
}

플레이어 상태

상태	값	설명
UNSTARTED	-1	비디오 시작 안됨
ENDED	0	비디오 종료됨
PLAYING	1	비디오 재생 중
PAUSED	2	비디오 일시 중지됨
BUFFERING	3	비디오 버퍼링 중
CUED	5	비디오 준비됨

품질 레벨

• small: 240p
• medium: 360p
• large: 480p
• hd720: 720p
• hd1080: 1080p
• highres: >1080p
• default: 자동 품질

모범 사례

1. 한 번 초기화: 플레이어 인스턴스를 한 번 생성하고 재사용하세요
2. 오류를 우아하게 처리: 오류 이벤트 리스너를 구현하세요
3. 정리: 컴포넌트 언마운트 시 플레이어를 제거하세요
4. 사용자 선호 존중: 사용자가 시작하지 않는 한 자동 재생하지 마세요
5. 재생 모니터링: 진행 상황을 추적하세요

플랫폼 참고사항

iOS

• iOS 9.0+ 에서 작동
• YouTube iframe API와 함께 WKWebView 사용
• 전체 화면 지원

Android

• Android 5.0 (API 21)+ 에서 작동
• YouTube iframe API와 함께 WebView 사용
• 전체 화면 지원

Web

• 직접 YouTube iframe 통합
• 전체 API 지원
• 최고의 성능