---
url: /1.x/ko/guide/getting-started/overview.md
---

# 1.x 개요

![react-native-youtube-bridge 데모](https://raw.githubusercontent.com/react-native-bridges/react-native-youtube-bridge/main/assets/example.gif)
1.x는 `YoutubePlayer` 컴포넌트, callback props, imperative ref를 중심으로 한 레거시 API입니다.

`react-native-youtube-bridge`는 [YouTube IFrame Player API](https://developers.google.com/youtube/iframe_api_reference)를 React Native 앱에서 쉽게 사용할 수 있게 감싼 라이브러리입니다.

## 주요 특징

- TypeScript 지원
- iOS, Android, Web 지원
- New Architecture 지원
- 네이티브 YouTube 플레이어 모듈 불필요
- YouTube IFrame Player API 기능 지원
- Expo 친화적 구성
- Inline HTML / 외부 WebView 렌더링 모드

기존 1.x 통합을 유지보수할 때 이 버전 문서를 사용하세요. 새 작업에는 2.x Hook 기반 API를 권장합니다.



---
url: /1.x/ko/guide/getting-started/installation.md
---

# 설치

:::warning 레거시 버전
1.x는 레거시 API입니다. 기존 1.x 통합을 유지보수하는 경우가 아니라면 최신 2.x 설치를 권장합니다.
:::

1.x 패키지를 설치합니다.


```sh [npm]
npm install react-native-youtube-bridge@1.x
```

```sh [yarn]
yarn add react-native-youtube-bridge@1.x
```

```sh [pnpm]
pnpm add react-native-youtube-bridge@1.x
```

```sh [bun]
bun add react-native-youtube-bridge@1.x
```

```sh [deno]
deno add npm:react-native-youtube-bridge@1.x
```

## peer dependency

iOS와 Android에서는 `react-native-webview`가 필요합니다.


```sh [npm]
npm install react-native-webview
```

```sh [yarn]
yarn add react-native-webview
```

```sh [pnpm]
pnpm add react-native-webview
```

```sh [bun]
bun add react-native-webview
```

```sh [deno]
deno add npm:react-native-webview
```

## 최소 조건

| 패키지                    | 버전         |
| ---------------------- | ---------- |
| `react`                | `>=16.8.0` |
| `react-native`         | `>=0.60.0` |
| `react-native-webview` | `>=11.0.0` |



---
url: /1.x/ko/guide/getting-started/quick-start.md
---

# 빠른 시작

## 설치


```sh [npm]
npm install react-native-youtube-bridge@1.x
```

```sh [yarn]
yarn add react-native-youtube-bridge@1.x
```

```sh [pnpm]
pnpm add react-native-youtube-bridge@1.x
```

```sh [bun]
bun add react-native-youtube-bridge@1.x
```

```sh [deno]
deno add npm:react-native-youtube-bridge@1.x
```

## 기본 플레이어

```tsx
import { YoutubePlayer } from 'react-native-youtube-bridge';

function App() {
  return <YoutubePlayer source="AbZH7XWDW_k" />;
}
```

## source 입력 형태

```tsx
<YoutubePlayer source="AbZH7XWDW_k" />
<YoutubePlayer source={{ videoId: 'AbZH7XWDW_k' }} />
<YoutubePlayer source={{ url: 'https://youtube.com/watch?v=AbZH7XWDW_k' }} />
```

## 다음 단계

- 컴포넌트 API는 [기본 사용법](/1.x/ko/guide/usage/basic-usage.md)에서 확인하세요.
- 플레이어 제어는 [플레이어 제어](/1.x/ko/guide/usage/player-controls.md)에서 확인하세요.
- 2.x로 이동하려면 [마이그레이션 가이드](/1.x/ko/guide/migration-from-1.x.md)를 참고하세요.



---
url: /1.x/ko/guide/getting-started/ai.md
---

# AI

AI가 이 라이브러리의 `1.x` 동작, 문서, 프로젝트 규칙을 더 잘 이해해서 개발이나 트러블슈팅 과정에서 더 정확한 도움을 줄 수 있도록, 이 프로젝트는 다음 기능들을 제공합니다.

## llms.txt

[`llms.txt`](https://llmstxt.org/)는 LLM이 프로젝트 문서를 더 쉽게 탐색하고 활용할 수 있도록 돕는 표준입니다. `1.x` 문서는 아래 파일을 사용하면 됩니다.

- [1.x/llms.txt](https://react-native-youtube-bridge-docs.pages.dev/1.x/ko/llms.txt): `1.x` 문서용 구조화된 인덱스 파일

```txt
https://react-native-youtube-bridge-docs.pages.dev/1.x/ko/llms.txt
```

- [1.x/llms-full.txt](https://react-native-youtube-bridge-docs.pages.dev/1.x/ko/llms-full.txt): `1.x` 문서 전체를 하나로 합친 파일

```txt
https://react-native-youtube-bridge-docs.pages.dev/1.x/ko/llms-full.txt
```

## Markdown docs

모든 문서 페이지는 AI에게 직접 전달할 수 있는 Markdown 버전도 함께 제공합니다.

예시:

```txt
https://react-native-youtube-bridge-docs.pages.dev/1.x/ko/guide/getting-started/overview.md
https://react-native-youtube-bridge-docs.pages.dev/1.x/ko/guide/getting-started/quick-start.md
https://react-native-youtube-bridge-docs.pages.dev/1.x/ko/guide/usage/player-controls.md
```

특정 기능만 물어볼 때는 전체 문서보다 관련 Markdown 페이지 하나를 제공하는 편이 더 효율적입니다.



---
url: /1.x/ko/guide/usage/basic-usage.md
---

# 기본 사용법

1.x는 `YoutubePlayer` 컴포넌트를 중심으로 사용합니다.

```tsx
import { YoutubePlayer } from 'react-native-youtube-bridge';

function App() {
  return <YoutubePlayer source="AbZH7XWDW_k" height={240} width="100%" />;
}
```

## source 입력

`source`는 비디오 ID, `{ videoId }`, `{ url }` 형태를 받을 수 있습니다.

```tsx
<YoutubePlayer source="AbZH7XWDW_k" />
<YoutubePlayer source={{ videoId: 'AbZH7XWDW_k' }} />
<YoutubePlayer source={{ url: 'https://youtube.com/watch?v=AbZH7XWDW_k' }} />
```



---
url: /1.x/ko/guide/usage/player-controls.md
---

# 플레이어 제어

1.x는 `ref`를 통해 플레이어를 제어합니다.

```tsx
import { useRef } from 'react';
import { Button, View } from 'react-native';
import { YoutubePlayer, type PlayerControls } from 'react-native-youtube-bridge';

function App() {
  const playerRef = useRef<PlayerControls>(null);

  return (
    <View>
      <YoutubePlayer ref={playerRef} source="AbZH7XWDW_k" />
      <Button title="Play" onPress={() => playerRef.current?.play()} />
      <Button title="Pause" onPress={() => playerRef.current?.pause()} />
      <Button title="Seek" onPress={() => playerRef.current?.seekTo(30, true)} />
    </View>
  );
}
```

## 주요 메서드

- `play`, `pause`, `stop`, `seekTo`
- `setVolume`, `getVolume`, `mute`, `unMute`, `isMuted`
- `getCurrentTime`, `getDuration`, `getVideoUrl`, `getVideoEmbedCode`
- `getPlaybackRate`, `setPlaybackRate`, `getAvailablePlaybackRates`
- `getPlayerState`, `getVideoLoadedFraction`
- `loadVideoById`, `cueVideoById`, `setSize`



---
url: /1.x/ko/guide/usage/handling-events.md
---

# 이벤트 처리

1.x에서는 이벤트를 `YoutubePlayer`의 callback prop으로 전달합니다.

> 안정적인 참조와 성능을 위해 callback은 `useCallback`으로 감싸는 것을 권장합니다.

```tsx
import { useCallback } from 'react';
import { YoutubePlayer, PlayerState } from 'react-native-youtube-bridge';

function App() {
  const handleReady = useCallback(() => {
    console.log('ready');
  }, []);

  const handleStateChange = useCallback((state: PlayerState) => {
    console.log('state', state);
  }, []);

  return (
    <YoutubePlayer
      source="AbZH7XWDW_k"
      onReady={handleReady}
      onStateChange={handleStateChange}
      onError={(error) => console.error(error)}
    />
  );
}
```

## Progress

`progressInterval`과 `onProgress`를 함께 사용하면 재생 진행률을 받을 수 있습니다.

```tsx
<YoutubePlayer
  source="AbZH7XWDW_k"
  progressInterval={1000}
  onProgress={(progress) => {
    console.log(progress.currentTime, progress.duration, progress.loadedFraction);
  }}
/>
```



---
url: /1.x/ko/guide/usage/player-config.md
---

# 플레이어 설정

`playerVars`로 YouTube 재생 환경을 설정합니다.

```tsx
<YoutubePlayer
  source="AbZH7XWDW_k"
  playerVars={{
    autoplay: true,
    controls: true,
    playsinline: true,
    rel: false,
    muted: true,
  }}
/>
```

주요 옵션은 `autoplay`, `controls`, `loop`, `muted`, `startTime`, `endTime`, `playsinline`, `rel`, `origin`입니다.



---
url: /1.x/ko/guide/usage/styling-and-layout.md
---

# 스타일과 레이아웃

`YoutubePlayer`는 크기와 플랫폼별 스타일 prop을 받습니다.

```tsx
<YoutubePlayer
  source="AbZH7XWDW_k"
  height={400}
  width="100%"
  style={{ borderRadius: 10 }}
  iframeStyle={{ aspectRatio: 16 / 9 }}
  webViewStyle={{ backgroundColor: 'transparent' }}
/>
```

- `iframeStyle`: Web 전용
- `webViewStyle`: iOS / Android 전용
- `webViewProps`: iOS / Android 전용



---
url: /1.x/ko/guide/usage/inline-html-vs-webview.md
---

# Inline HTML vs WebView

iOS와 Android에서 1.x는 두 가지 렌더링 방식을 지원합니다.

## Inline HTML mode

```tsx
<YoutubePlayer source="AbZH7XWDW_k" useInlineHtml />
```

- 기본 모드
- 앱 내부에서 HTML을 직접 로드합니다.

## External WebView mode

```tsx
<YoutubePlayer
  source="AbZH7XWDW_k"
  useInlineHtml={false}
  webViewUrl="https://your-custom-player.com"
/>
```

- 외부 플레이어 페이지를 로드합니다.
- 기본 호스팅 페이지: `https://react-native-youtube-bridge.pages.dev`
- inline HTML에서 embed 제한이나 origin 제약을 만날 때 유용합니다.



---
url: /1.x/ko/guide/usage/custom-webview-player.md
---

# Custom WebView Player

직접 외부 플레이어 페이지를 호스팅해야 한다면 `@react-native-youtube-bridge/web`를 사용합니다.

```bash
npm install @react-native-youtube-bridge/web
```

```tsx
import { YoutubePlayer } from '@react-native-youtube-bridge/web';

function CustomPlayerPage() {
  return <YoutubePlayer />;
}

export default CustomPlayerPage;
```

이후 native 앱에서 호스팅 URL을 전달합니다.

```tsx
<YoutubePlayer
  source="AbZH7XWDW_k"
  useInlineHtml={false}
  webViewUrl="https://your-custom-player.com"
/>
```



---
url: /1.x/ko/guide/usage/metadata-with-oembed.md
---

# oEmbed 메타데이터

`useYoutubeOEmbed`로 YouTube 메타데이터를 선택적으로 가져올 수 있습니다.

```tsx
import { useYoutubeOEmbed } from 'react-native-youtube-bridge';

function App() {
  const { oEmbed, isLoading, error } = useYoutubeOEmbed(
    'https://www.youtube.com/watch?v=AbZH7XWDW_k',
  );

  if (isLoading) return null;
  if (error) return null;

  return <Text>{oEmbed?.title}</Text>;
}
```



---
url: /1.x/ko/guide/usage/errors-and-troubleshooting.md
---

# 에러와 트러블슈팅

이 페이지는 2.x 트러블슈팅 페이지에서 1.x 문서로 버전을 전환했을 때 404로 떨어지지 않도록 제공합니다.

## Embed not allowed 또는 빈 플레이어

inline HTML 모드에서 영상이 로드되지 않으면 호스팅된 플레이어 페이지를 사용하는 WebView 모드로 전환해 보세요.

```tsx
<YoutubePlayer
  source="AbZH7XWDW_k"
  useInlineHtml={false}
  webViewUrl="https://react-native-youtube-bridge.pages.dev"
/>
```

## 이벤트 콜백이 예상과 다르게 동작할 때

렌더마다 불안정한 callback reference가 전달되지 않도록 이벤트 콜백은 `useCallback`으로 감싸세요.

```tsx
const handleReady = useCallback(() => {
  console.log('Player is ready');
}, []);

<YoutubePlayer source="AbZH7XWDW_k" onReady={handleReady} />;
```

## Progress가 업데이트되지 않을 때

`progressInterval`에 양수 interval을 전달하지 않으면 progress tracking은 비활성화됩니다.

```tsx
<YoutubePlayer source="AbZH7XWDW_k" progressInterval={1000} onProgress={handleProgress} />
```

## 새 수정은 2.x를 우선하세요

1.x는 레거시 API입니다. 새 통합을 시작하거나 안전하게 전환할 수 있다면 [2.x 트러블슈팅 가이드](/1.x/ko/guide/usage/errors-and-troubleshooting.md)와 [마이그레이션 가이드](/1.x/ko/guide/migration-from-1.x.md)를 참고하세요.



---
url: /1.x/ko/guide/usage/api-reference.md
---

# API 레퍼런스

이 페이지는 레거시 1.x 컴포넌트 API를 요약하고, 2.x API reference에서 1.x로 버전을 전환했을 때 404로 떨어지지 않도록 제공합니다.

## 주요 export

```ts
import { YoutubePlayer, useYoutubeOEmbed } from 'react-native-youtube-bridge';
import type {
  PlayerControls,
  PlayerState,
  ProgressData,
  YouTubeError,
} from 'react-native-youtube-bridge';
```

## 핵심 컴포넌트

### `YoutubePlayer`

YouTube 플레이어를 직접 렌더링하고 `ref`를 통해 imperative control을 제공합니다.

```tsx
const playerRef = useRef<PlayerControls>(null);

<YoutubePlayer ref={playerRef} source="AbZH7XWDW_k" />;
```

## 주요 props

- `source`: YouTube video ID, YouTube URL, 또는 source object.
- `playerVars`: YouTube embedded player parameters.
- `height` / `width`: 플레이어 크기.
- `style`: React Native 플레이어 컨테이너 스타일.
- `iframeStyle`: web에서 iframe wrapper 스타일.
- `webViewStyle`: iOS와 Android에서 WebView 스타일.
- `webViewProps`: iOS와 Android에서 추가 WebView props.
- `useInlineHtml`: iOS와 Android에서 inline HTML 또는 외부 WebView 모드 선택.
- `webViewUrl`: 커스텀 WebView source URL 또는 inline HTML `baseUrl`.
- `progressInterval`: 양수 interval을 설정하면 `onProgress`를 활성화합니다.

## 이벤트 props

- `onReady`
- `onStateChange`
- `onError`
- `onProgress`
- `onPlaybackRateChange`
- `onPlaybackQualityChange`
- `onAutoplayBlocked`

이벤트 핸들러는 불안정한 callback reference를 피하기 위해 `useCallback`으로 감싸세요.

## Ref 메서드

- `play`, `pause`, `stop`, `seekTo`
- `setVolume`, `getVolume`, `mute`, `unMute`, `isMuted`
- `getCurrentTime`, `getDuration`, `getVideoUrl`, `getVideoEmbedCode`
- `getPlaybackRate`, `setPlaybackRate`, `getAvailablePlaybackRates`
- `getPlayerState`, `getVideoLoadedFraction`
- `loadVideoById`, `cueVideoById`, `setSize`

## 메타데이터 훅

`useYoutubeOEmbed(url?)`은 YouTube URL의 선택적 oEmbed 메타데이터를 가져옵니다.

## 새 프로젝트

1.x는 레거시입니다. 새 프로젝트는 [2.x API 레퍼런스](/1.x/ko/guide/usage/api-reference.md)와 `useYouTubePlayer` + `YoutubeView`로 시작하세요.



---
url: /1.x/ko/guide/migration-from-1.x.md
---

# 2.x로 마이그레이션

2.x는 기존 component/ref 모델을 hook-and-view 모델로 바꿉니다.

> \[!tip]
> 이 페이지는 1.x 문서 안에서 보는 짧은 마이그레이션 안내입니다. 전체 최신 마이그레이션 내용은 <a href="/ko/guide/migration-from-1.x.html">2.x의 1.x 마이그레이션 가이드</a>를 참고하세요.

| 1.x                   | 2.x                                |
| --------------------- | ---------------------------------- |
| `YoutubePlayer` 컴포넌트  | `useYouTubePlayer` + `YoutubeView` |
| callback props        | `useYouTubeEvent`                  |
| `ref.current?.play()` | `player.play()`                    |
| 컴포넌트 props에 설정 전달     | hook config에 플레이어 옵션 전달            |

## 컴포넌트 교체

Before:

```tsx
import { YoutubePlayer } from 'react-native-youtube-bridge';

<YoutubePlayer source="AbZH7XWDW_k" />;
```

After:

```tsx
import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';

const player = useYouTubePlayer('AbZH7XWDW_k');

<YoutubeView player={player} />;
```

## 이벤트 마이그레이션

Before:

```tsx
<YoutubePlayer onReady={handleReady} onStateChange={handleStateChange} />
```

After:

```tsx
useYouTubeEvent(player, 'ready', handleReady);
useYouTubeEvent(player, 'stateChange', handleStateChange);
```

## 제어 메서드 마이그레이션

Before:

```tsx
playerRef.current?.play();
```

After:

```tsx
player.play();
```



---
url: /1.x/ko/index.md
---