시작하기

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

        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 지원 설정으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

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

그다음 아래 prompt를 사용하세요:

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

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

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
});

자주 하는 실수

리스너: 화면이 unmount될 때 핸들을 제거하세요.
한 번만 초기화: 앱 부트스트랩 시 setup을 실행하세요.
단일 진실 공급원: 신뢰 src/definitions.ts GitHub 레포지토리에서.

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

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

활성화하면 플러그인이 동기화/업데이트 중에 Capacitor를 패치하여, 가로채기된 YouTube 요청에 유효한 Referer 헤더가 포함되도록 합니다.

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

오직 youtube.com, youtube-nocookie.com, 그리고 youtu.be 요청에만 영향을 미칩니다.
이미 Referer 헤더가 정의된 요청은 기존 값을 유지합니다.
refererHeader 은(는) 선택 사항이며 기본값은 https://www.youtube.com.
Capacitor 지원 8.x 설치된 iOS 및 Android 플랫폼용.

API 개요

`initialize`

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

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

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

`destroy`

플레이어 인스턴스를 제거하고 리소스를 해제합니다.

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`

버퍼링된 비디오의 비율을 가져옵니다. 더 이상 사용되지 않는 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;
}

기준 소스

이 페이지는 플러그인의 src/definitions.ts에서 생성되었습니다. public API가 업스트림에서 변경되면 동기화를 다시 실행하세요.

Getting Started에서 계속하기

사용 중인 경우 시작하기 대시보드와 API 운영을 계획하려면, 이를 다음 항목과 연결하세요: @capgo/capacitor-youtube-player 사용하기 @capgo/capacitor-youtube-player를 사용하여 네이티브 기능을 구현할 때, API 개요 API Overview의 구현 상세 내용은 소개 Introduction의 구현 상세 내용은 API 키 API Keys의 구현 세부 사항은, 디바이스 Devices의 구현 세부 사항은.