시작

설치 명령어와 이 플러그인의 전체 마크다운 가이드를 포함한 설정 명령어를 복사하세요.

        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 기능을 추가하려면 다음 명령어를 사용하세요:

npx 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.

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

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

Import

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

메인 WebView에서 YouTube Referer 차단을 고치세요

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

활성화 시 플러그인은 Capacitor을 동기화/업데이트 중에 패치하여 Capacitor을 포함하는 유투브 요청을 유효한 Referer header.

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

Only youtube.com, youtube-nocookie.com, 그리고 youtu.be 이미 __CAPGO_KEEP_0__을 정의한 요청은 원래 값을 유지합니다.
__CAPGO_KEEP_0__은 선택사항이며 기본값은 Referer 원본 값이 유지됩니다.
refererHeader __CAPGO_KEEP_0__ 개요 https://www.youtube.com.
Capacitor 8.x __CAPGO_KEEP_0__

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`

현재 재생 중인 비디오를 멈춥니다. 재생 상태는 PAUSED (2)로 끝납니다. 이미 ENDED (0) 상태라면 그대로 유지됩니다.

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로 비디오를 큐합니다. 이미지와 플레이어를 준비하지만 비디오를 요청할 때까지 재생하지 않습니다.

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`

URL로 플레이리스트를 큐하고 재생하지 않습니다. 플레이리스트를 로드하고 첫 번째 비디오를 준비합니다.

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

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

`loadPlaylist`

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

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과 같은 deprecated 함수보다 더 신뢰할 수 있습니다.

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`

Section titled “setPlaybackQuality”

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

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

`getVideoUrl`

Section titled “getDuration”

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 요소를 가져옵니다. 웹 플랫폼 전용.

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

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

`addEventListener`

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

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

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

`removeEventListener`

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

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. API 업스트림에서 변경되면 다시 싱크를 실행하세요.

시작부터 계속하기

시작부터 계속하기 시작부터 계속하기 API와 __CAPGO_KEEP_1__-유튜브 플레이어를 사용하여 capgo와 capacitor-유튜브 플레이어를 사용하여 Capacitor의 내장 기능인 @capgo/capacitor-youtube-player을 사용하기 위해 API 개요 API 개요 소개 __CAPGO_KEEP_0__ API 키 implementation 세부 정보를 위한 API 키 기기 implementation 세부 정보를 위한 기기