시작하기

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-youtube-player`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/youtube-player/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

그런 다음 아래 프롬프트를 사용하세요:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-youtube-player` plugin in my project.

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

bun add @capgo/capacitor-youtube-player
bunx cap sync

가져오기

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

빠른 시작

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

await YoutubePlayer.initialize({
  playerId: 'my-player',
  videoId: 'dQw4w9WgXcQ',
  playerSize: { width: 640, height: 360 },
  privacyEnhanced: true
});

자주 하는 실수

리스너: 화면이 언마운트될 때 핸들을 제거합니다.
한 번만 초기화: 앱 부트스트랩 시 setup을 실행하세요.
신뢰할 수 있는 소스: 신뢰 src/definitions.ts GitHub 레포지토리에서.

메인 WebView의 YouTube Referer 차단 문제 해결

플러그인 내부에서는 YouTube가 잘 작동하지만, 동일한 앱에서 Capacitor의 메인 WebView를 통해 YouTube 페이지, 임베드 또는 API를 로드할 때 실패한다면 patchRefererHeader Capacitor 설정에서 활성화하세요.

이 기능을 활성화하면, 동기화/업데이트 중에 플러그인이 Capacitor를 패치하여 가로챈 YouTube 요청에 유효한 Referer header.

{
  "plugins": {
    "YoutubePlayer": {
      "patchRefererHeader": true,
      "refererHeader": "https://www.youtube.com"
    }
  }
}

만 youtube.com, youtube-nocookie.com, 그리고 youtu.be 요청이 영향을 받습니다.
이미 header를 정의한 Referer 요청은 기존 값을 유지합니다.
refererHeader 은 선택 사항이며 기본값은 https://www.youtube.com.
Capacitor에서 지원됩니다 8.x 설치된 iOS 및 Android 플랫폼에 대해.

API 개요

`initialize`

새 YouTube player 인스턴스를 초기화합니다.

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

await YoutubePlayer.initialize({
  playerId: 'my-player',
  videoId: 'dQw4w9WgXcQ',
  playerSize: { width: 640, height: 360 },
  privacyEnhanced: true
});

`destroy`

player 인스턴스를 제거하고 리소스를 해제합니다.

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

const result = await YoutubePlayer.destroy({ playerId: 'player-id-123' });
console.log(result);

`stopVideo`

비디오 재생을 중단하고 로딩을 취소합니다. 가급적 사용하지 마세요. 보통 pauseVideo()를 권장합니다.

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

const result = await YoutubePlayer.stopVideo({ playerId: 'player-id-123' });
console.log(result);

`playVideo`

현재 대기 중이거나 로드된 비디오를 재생합니다. 최종 플레이어 상태는 PLAYING (1)이 됩니다.

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

const result = await YoutubePlayer.playVideo({ playerId: 'player-id-123' });
console.log(result);

`pauseVideo`

현재 재생 중인 비디오를 일시 정지합니다. 이미 ENDED (0) 상태가 아니라면, 최종 플레이어 상태는 PAUSED (2)가 됩니다.

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

const result = await YoutubePlayer.pauseVideo({ playerId: 'player-id-123' });
console.log(result);

`seekTo`

비디오의 특정 시점으로 이동합니다. 플레이어가 일시 정지 상태라면 그대로 유지되고, 재생 중이라면 계속 재생됩니다.

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

const result = await YoutubePlayer.seekTo({
  playerId: 'player-id-123',
  seconds: 10,
  allowSeekAhead: true,
});
console.log(result);

`loadVideoById`

YouTube ID로 비디오를 로드하고 재생합니다.

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

const result = await YoutubePlayer.loadVideoById({
  playerId: 'player-id-123',
  options: { videoId: 'video-id-123' },
});
console.log(result);

`cueVideoById`

ID로 비디오를 큐에 추가하되 재생하지 않습니다. 썸네일을 로드하고 플레이어를 준비하지만, playVideo()가 호출될 때까지 비디오를 요청하지 않습니다.

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

const result = await YoutubePlayer.cueVideoById({
  playerId: 'player-id-123',
  options: { videoId: 'video-id-123' },
});
console.log(result);

`loadVideoByUrl`

전체 URL로 비디오를 로드하고 재생합니다.

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

const result = await YoutubePlayer.loadVideoByUrl({
  playerId: 'player-id-123',
  options: { mediaContentUrl: 'https://example.com' },
});
console.log(result);

`cueVideoByUrl`

재생하지 않고 URL로 비디오를 대기시킵니다.

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

const result = await YoutubePlayer.cueVideoByUrl({
  playerId: 'player-id-123',
  options: { mediaContentUrl: 'https://example.com' },
});
console.log(result);

`cuePlaylist`

재생하지 않고 플레이리스트를 큐에 추가합니다. 플레이리스트를 로드하고 첫 번째 동영상을 준비합니다.

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

const result = await YoutubePlayer.cuePlaylist({
  playerId: 'player-id-123',
  playlistOptions: { listType: 'playlist' },
});
console.log(result);

`loadPlaylist`

플레이리스트를 로드하고 재생합니다.

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

const result = await YoutubePlayer.loadPlaylist({
  playerId: 'player-id-123',
  playlistOptions: { listType: 'playlist' },
});
console.log(result);

`nextVideo`

플레이리스트의 다음 영상을 재생합니다.

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

const result = await YoutubePlayer.nextVideo({ playerId: 'player-id-123' });
console.log(result);

`previousVideo`

플레이리스트의 이전 영상을 재생합니다.

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

const result = await YoutubePlayer.previousVideo({ playerId: 'player-id-123' });
console.log(result);

`playVideoAt`

인덱스로 플레이리스트의 특정 영상을 재생합니다.

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

const result = await YoutubePlayer.playVideoAt({
  playerId: 'player-id-123',
  index: 1,
});
console.log(result);

`mute`

플레이어 오디오를 음소거합니다.

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

const result = await YoutubePlayer.mute({ playerId: 'player-id-123' });
console.log(result);

`unMute`

플레이어 오디오의 음소거를 해제합니다.

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

const result = await YoutubePlayer.unMute({ playerId: 'player-id-123' });
console.log(result);

`isMuted`

플레이어가 현재 음소거 상태인지 확인합니다.

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

const result = await YoutubePlayer.isMuted({ playerId: 'player-id-123' });
console.log(result);

`setVolume`

플레이어 볼륨을 설정합니다.

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

const result = await YoutubePlayer.setVolume({
  playerId: 'player-id-123',
  volume: 0.5,
});
console.log(result);

`getVolume`

현재 플레이어의 볼륨 레벨을 가져옵니다. 플레이어가 음소거 상태여도 볼륨 값을 반환합니다.

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

const result = await YoutubePlayer.getVolume({ playerId: 'player-id-123' });
console.log(result);

`setSize`

플레이어 크기를 픽셀 단위로 설정합니다.

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

const result = await YoutubePlayer.setSize({
  playerId: 'player-id-123',
  width: 1080,
  height: 1920,
});
console.log(result);

`getPlaybackRate`

현재 재생 속도를 가져옵니다.

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

const result = await YoutubePlayer.getPlaybackRate({ playerId: 'player-id-123' });
console.log(result);

`setPlaybackRate`

재생 속도를 설정합니다.

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

const result = await YoutubePlayer.setPlaybackRate({
  playerId: 'player-id-123',
  suggestedRate: 1,
});
console.log(result);

`getAvailablePlaybackRates`

현재 비디오의 사용 가능한 재생 속도 목록을 가져옵니다.

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

const result = await YoutubePlayer.getAvailablePlaybackRates({ playerId: 'player-id-123' });
console.log(result);

`setLoop`

플레이리스트 반복 재생을 활성화하거나 비활성화합니다. 활성화하면 마지막 비디오가 끝나면 처음부터 다시 재생됩니다.

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

const result = await YoutubePlayer.setLoop({
  playerId: 'player-id-123',
  loopPlaylists: true,
});
console.log(result);

`setShuffle`

플레이리스트 셔플을 활성화하거나 비활성화합니다.

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

const result = await YoutubePlayer.setShuffle({
  playerId: 'player-id-123',
  shufflePlaylist: true,
});
console.log(result);

`getVideoLoadedFraction`

버퍼링된 비디오의 비율을 가져옵니다. 비권장(deprecated)된 getVideoBytesLoaded/getVideoBytesTotal보다 더 신뢰할 수 있습니다.

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

const result = await YoutubePlayer.getVideoLoadedFraction({ playerId: 'player-id-123' });
console.log(result);

`getPlayerState`

플레이어의 현재 상태를 가져옵니다.

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

const result = await YoutubePlayer.getPlayerState({ playerId: 'player-id-123' });
console.log(result);

`getAllPlayersEventsState`

모든 활성 플레이어의 이벤트 상태를 가져옵니다. 여러 플레이어 인스턴스를 추적하는 데 유용합니다.

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

const result = await YoutubePlayer.getAllPlayersEventsState();
console.log(result);

`getCurrentTime`

현재 재생 위치를 초 단위로 가져옵니다.

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

const result = await YoutubePlayer.getCurrentTime({ playerId: 'player-id-123' });
console.log(result);

`toggleFullScreen`

전체 화면 모드를 켜거나 끕니다.

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

const result = await YoutubePlayer.toggleFullScreen({
  playerId: 'player-id-123',
  isFullScreen: true,
});
console.log(result);

`getPlaybackQuality`

현재 재생 품질을 가져옵니다.

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

const result = await YoutubePlayer.getPlaybackQuality({ playerId: 'player-id-123' });
console.log(result);

`setPlaybackQuality`

권장 재생 품질을 설정합니다. 실제 품질은 네트워크 상태에 따라 달라질 수 있습니다.

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

const result = await YoutubePlayer.setPlaybackQuality({
  playerId: 'player-id-123',
  suggestedQuality: IPlaybackQuality.SMALL,
});
console.log(result);

`getAvailableQualityLevels`

현재 비디오의 사용 가능한 품질 레벨 목록을 가져옵니다.

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

const result = await YoutubePlayer.getAvailableQualityLevels({ playerId: 'player-id-123' });
console.log(result);

`getDuration`

현재 비디오의 재생 시간을 초 단위로 가져옵니다.

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

const result = await YoutubePlayer.getDuration({ playerId: 'player-id-123' });
console.log(result);

`getVideoUrl`

현재 비디오의 YouTube.com URL을 가져옵니다.

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

const result = await YoutubePlayer.getVideoUrl({ playerId: 'player-id-123' });
console.log(result);

`getVideoEmbedCode`

현재 비디오의 임베드 code를 가져옵니다. HTML iframe 임베드 code를 반환합니다.

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

const result = await YoutubePlayer.getVideoEmbedCode({ playerId: 'player-id-123' });
console.log(result);

`getPlaylist`

현재 재생 목록의 비디오 ID 배열을 가져옵니다.

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

const result = await YoutubePlayer.getPlaylist({ playerId: 'player-id-123' });
console.log(result);

`getPlaylistIndex`

재생 목록에서 현재 재생 중인 비디오의 인덱스를 가져옵니다.

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

const result = await YoutubePlayer.getPlaylistIndex({ playerId: 'player-id-123' });
console.log(result);

`getIframe`

플레이어의 iframe DOM 요소를 가져옵니다. Web 플랫폼 전용.

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

const result = await YoutubePlayer.getIframe({ playerId: 'player-id-123' });
console.log(result);

`addEventListener`

플레이어에 이벤트 리스너를 추가합니다. Web 플랫폼 전용.

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

YoutubePlayer.addEventListener({
  playerId: 'my-player',
  eventName: 'onStateChange',
  listener: (event) => {
  console.log('Player state:', event.data);
  },
});

`removeEventListener`

플레이어에서 이벤트 리스너를 제거합니다. Web 플랫폼 전용.

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

await YoutubePlayer.removeEventListener({
  playerId: 'player-id-123',
  eventName: 'onReady',
  listener: (event) => {
    console.log(event);
  },
});

타입 레퍼런스

`PlayerIdOptions`

export interface PlayerIdOptions {
  playerId: string;
}

`SeekToOptions`

export interface SeekToOptions extends PlayerIdOptions {
  playerId: string;
  seconds: number;
  allowSeekAhead: boolean;
}

`VideoByIdMethodOptions`

export interface VideoByIdMethodOptions extends PlayerIdOptions {
  playerId: string;
  options: IVideoOptionsById;
}

`VideoByUrlMethodOptions`

export interface VideoByUrlMethodOptions extends PlayerIdOptions {
  playerId: string;
  options: IVideoOptionsByUrl;
}

`PlaylistMethodOptions`

export interface PlaylistMethodOptions extends PlayerIdOptions {
  playerId: string;
  playlistOptions: IPlaylistOptions;
}

`PlayVideoAtOptions`

export interface PlayVideoAtOptions extends PlayerIdOptions {
  playerId: string;
  index: number;
}

`SetVolumeOptions`

export interface SetVolumeOptions extends PlayerIdOptions {
  playerId: string;
  volume: number;
}

`SetSizeOptions`

export interface SetSizeOptions extends PlayerIdOptions {
  playerId: string;
  width: number;
  height: number;
}

`SetPlaybackRateOptions`

export interface SetPlaybackRateOptions extends PlayerIdOptions {
  playerId: string;
  suggestedRate: number;
}

`SetLoopOptions`

export interface SetLoopOptions extends PlayerIdOptions {
  playerId: string;
  loopPlaylists: boolean;
}

`SetShuffleOptions`

export interface SetShuffleOptions extends PlayerIdOptions {
  playerId: string;
  shufflePlaylist: boolean;
}

`ToggleFullScreenOptions`

export interface ToggleFullScreenOptions extends PlayerIdOptions {
  playerId: string;
  isFullScreen: boolean | null | undefined;
}

Source of Truth

이 페이지는 플러그인의 src/definitions.tsupstream에서 public API가 변경되면 sync를 다시 실행하세요.

시작하기 다음 단계

사용 중이라면 시작하기 대시보드 및 API 운영을 계획하려면, 이를 다음과 연결하세요 @capgo/capacitor-youtube-player 사용하기 @capgo/capacitor-youtube-player 사용 시 네이티브 기능을 위해, API 개요 구현 세부 사항은 API 개요에서 소개 구현 세부 사항은 소개에서 API 키 API Keys의 구현 세부 사항은, 기기 Devices의 구현 세부 사항은.