diff --git a/.changeset/funny-moons-hear.md b/.changeset/funny-moons-hear.md
index 9aa8d94..57b9b47 100644
--- a/.changeset/funny-moons-hear.md
+++ b/.changeset/funny-moons-hear.md
@@ -7,19 +7,127 @@
 
 feat!: introduce hooks-based API for v2.0
 
-BREAKING CHANGE: Complete API redesign with React hooks
+> [!important]
+> BREAKING CHANGE: **Complete API Redesign with React Hooks**
 
-- Replace `YoutubePlayer` component with `YoutubeView` + `useYouTubePlayer` hook
-- Add `useYouTubeEvent` hook for reactive event handling
-- Remove ref-based imperative API in favor of declarative approach
-- Simplify component props and reduce coupling between components
-- Follow expo patterns for better DX
+#### New Hooks-Based Architecture
 
-Migration required from v1:
+- **`useYouTubePlayer(videoId, config)`** - Creates a player instance with declarative configuration
+- **`useYouTubeEvent(player, eventName, intervalOrDefault?, deps?)`** - Reactive event handling with complete type inference
+- **`YoutubeView`** - Simplified view component that accepts a player instance
 
-- `YoutubePlayer` → `YoutubeView` + `useYouTubePlayer()`
-- Event props → `useYouTubeEvent()` hooks
-- `playerRef.current.method()` → `player.method()`
+#### Migration from v1 to v2
 
-Fixes: Memory leaks, complex state management, tight coupling
-Improves: Developer experience, maintainability, performance
+**Before (v1):**
+```jsx
+// Imperative, ref-based API
+const playerRef = useRef<PlayerControls>(null);
+
+<YoutubePlayer
+  ref={playerRef}
+  source={videoId}
+  onReady={handleReady}
+  onStateChange={handleStateChange}
+  onProgress={handleProgress}
+  playerVars={{ autoplay: true }}
+/>
+
+// Manual event handlers and state management
+const [isPlaying, setIsPlaying] = useState(false);
+const handleStateChange = (state) => setIsPlaying(state === PlayerState.PLAYING);
+```
+
+**After (v2):**
+```jsx
+// Declarative, hooks-based API
+const player = useYouTubePlayer(videoId, {
+  autoplay: true,
+  controls: true,
+  playsinline: true
+});
+
+<YoutubeView player={player} />
+
+// Reactive state with automatic updates - two usage patterns:
+
+// 1. State-based (returns reactive values)
+const playbackRate = useYouTubeEvent(player, 'playbackRateChange', 1);
+const progress = useYouTubeEvent(player, 'progress', 1000); // 1000ms interval
+const state = useYouTubeEvent(player, 'stateChange');
+
+const isPlaying = state === PlayerState.PLAYING;
+
+// 2. Callback-based (for side effects)
+useYouTubeEvent(player, 'ready', (playerInfo) => {
+  console.log('Player ready:', playerInfo);
+});
+
+useYouTubeEvent(player, 'error', (error) => {
+  console.error('Player error:', error);
+});
+```
+
+### ✨ New Features
+
+- **Declarative Configuration**: Configure player options directly in `useYouTubePlayer` hook
+- **Automatic State Management**: No need to manually manage state for common use cases
+- **Reactive Events**: `useYouTubeEvent` with two usage patterns - state-based for reactive values and callback-based for side effects
+- **Better TypeScript Support**: Improved type inference and autocomplete
+- **Reduced Boilerplate**: Significantly less code required for common operations
+- **Automatic Cleanup**: Hooks handle cleanup automatically, preventing memory leaks
+
+### 🎯 Improvements
+
+- **Reduced Coupling**: Eliminated ref dependencies between parent and child components
+- **Simplified API**: Fewer props to manage, more intuitive usage patterns
+- **Better Developer Experience**: Following established React Native patterns (expo-audio, expo-video)
+- **Performance**: More efficient event handling with automatic cleanup
+- **Maintainability**: Cleaner separation of concerns
+
+### 📦 Component Changes
+
+#### Removed
+- ❌ `YoutubePlayer` component (replaced by `YoutubeView`)
+- ❌ `PlayerControls` ref interface
+- ❌ Direct event props (`onReady`, `onStateChange`, `onProgress`, etc.)
+
+#### Added
+- ✅ `YoutubeView` component
+- ✅ `useYouTubePlayer` hook
+- ✅ `useYouTubeEvent` hook
+- ✅ Simplified prop interface
+
+### 📚 Migration Guide
+
+For detailed migration examples and step-by-step instructions, see our [Migration Guide](/packages/react-native-youtube-bridge/docs/migration-v2.md).
+
+Key migration steps:
+1. **Replace `YoutubePlayer` with `YoutubeView` + `useYouTubePlayer`**
+2. **Convert event props to `useYouTubeEvent` hooks** (state-based or callback-based)
+3. **Move `playerVars` to `useYouTubePlayer` config**
+4. **Replace ref-based method calls with direct player method calls**
+5. **Remove manual state management for events**
+
+### ⚠️ Breaking Changes
+
+- **API Surface**: Complete API redesign, no backward compatibility
+- **Event Handling**: Manual event listeners replaced with reactive hooks
+- **Component Structure**: `YoutubePlayer` split into `YoutubeView` + hooks
+
+### 🐛 Bug Fixes
+- Fixed memory leaks from improper event cleanup
+- Better handling of rapid video ID changes
+- Manage multiple players independently
+
+### 📖 Documentation
+- Complete API documentation rewrite
+- Added migration guide from v1
+- Updated all examples to use v2 API
+- Added TypeScript usage examples
+
+---
+
+## Previous Versions
+
+### [1.x.x] - Legacy Version
+See [v1 documentation](/packages/react-native-youtube-bridge/docs/v1.md) for the previous imperative API.
diff --git a/.changeset/tired-papayas-sleep.md b/.changeset/tired-papayas-sleep.md
deleted file mode 100644
index 14cd9ba..0000000
--- a/.changeset/tired-papayas-sleep.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"@react-native-youtube-bridge/core": major
----
-
-feat: create Store Class for YouTube iframe state using useSyncExternalStore
diff --git a/README-ko_kr.md b/README-ko_kr.md
index 3784e9e..e16e4ce 100644
--- a/README-ko_kr.md
+++ b/README-ko_kr.md
@@ -2,6 +2,9 @@
 
 > [English](./README.md) | 한국어
 
+> [!note]
+> **V1 사용자:** [V1 문서](/packages/react-native-youtube-bridge/docs/v1.md) | [V2 마이그레이션 가이드](/packages/react-native-youtube-bridge/docs/migration-v2.md)
+
 ## 개요
 React Native에서 YouTube 플레이어를 사용하려면 복잡한 설정이 필요합니다.   
 하지만 현재 지속적으로 유지보수되고 있는 React Native용 YouTube 플레이어 라이브러리가 없는 상황입니다. (가장 인기 있는 react-native-youtube-iframe의 [최근 릴리즈는 2023년 07월 02일](https://github.com/LonelyCpp/react-native-youtube-iframe/releases/tag/v2.3.0))   
@@ -13,7 +16,8 @@ React Native에서 YouTube 플레이어를 사용하려면 복잡한 설정이 
 - ✅ New Architecture 지원
 - ✅ YouTube 네이티브 플레이어 모듈 없이도 사용 가능
 - ✅ 다양한 [YouTube iframe Player API](https://developers.google.com/youtube/iframe_api_reference) 기능 지원
-- ✅ 개발자 친화적인 API 제공
+- ✅ 다중 인스턴스 지원 - 여러 플레이어를 독립적으로 관리 가능
+- ✅ Expo의 접근 방식과 매우 유사한 직관적이고 사용하기 쉬운 Hook 기반 API 제공
 - ✅ Expo 지원
 - ✅ 유연한 렌더링 모드 (인라인 HTML & 웹뷰)
 
@@ -42,96 +46,91 @@ bun add react-native-youtube-bridge
 ## 사용법
 
 ```tsx
-import { YoutubePlayer } from 'react-native-youtube-bridge';
+import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';
 
 function App() {
+  const videoIdOrUrl = 'AbZH7XWDW_k'
+
+  // OR useYouTubePlayer({ videoId: 'AbZH7XWDW_k' })
+  // OR useYouTubePlayer({ url: 'https://youtube.com/watch?v=AbZH7XWDW_k' })
+  const player = useYouTubePlayer(videoIdOrUrl);
+
   return (
-    <YoutubePlayer 
-      source={source} // youtube videoId or url
-      // OR source={{ videoId: 'AbZH7XWDW_k' }}
-      // OR source={{ url: 'https://youtube.com/watch?v=AbZH7XWDW_k' }}
-    />
-  )
+    <YoutubeView player={player} />
+  );
 }
 ```
 
 ### 이벤트
-YouTube iframe API의 상태 변화를 애플리케이션에 전달하기 위해 [이벤트](https://developers.google.com/youtube/iframe_api_reference#Events)를 발생시킵니다. 콜백 함수를 통해 원하는 이벤트를 구독할 수 있습니다.   
+YouTube iframe API의 상태 변화를 애플리케이션에 전달하기 위해 [이벤트](https://developers.google.com/youtube/iframe_api_reference#Events)를 발생시킵니다.   
 
-> 🔔 Note - 성능 최적화 및 비정상 동작 방지를 위해 콜백 함수는 `useCallback`으로 감싸주세요.
+`useYouTubeEvent` hook을 사용하여 완벽한 타입 추론을 지원하며, 두 가지 방법으로 이벤트를 쉽게 감지하여 사용할 수 있습니다.
 
 ```tsx
-function App() {
-  const playerRef = useRef<PlayerControls>(null);
-
-  const handleReady = useCallback(() => {
-    console.log('플레이어 준비 완료!');
-  }, []);
+import { YoutubeView, useYouTubeEvent, useYouTubePlayer } from 'react-native-youtube-bridge';
 
-  const handleStateChange = useCallback((state: PlayerState) => {
-    console.log('플레이어 상태 변경:', state);
-  }, []);
+function App() {
+  const player = useYouTubePlayer(videoIdOrUrl);
 
-  const handlePlaybackRateChange = useCallback((rate: number) => {
-    console.log('재생 속도 변경:', rate);
-  }, []);
+  const playbackRate = useYouTubeEvent(player, 'playbackRateChange', 1);
+  const progress = useYouTubeEvent(player, 'progress', progressInterval);
 
-  const handlePlaybackQualityChange = useCallback((quality: string) => {
-    console.log('재생 품질 변경:', quality);
-  }, []);
+  useYouTubeEvent(player, 'ready', (playerInfo) => {
+    console.log('Player is ready!');
+    Alert.alert('Alert', 'YouTube player is ready!');
+  });
 
-  const handleAutoplayBlocked = useCallback(() => {
-    console.log('자동 재생이 차단되었습니다');
-  }, []);
+  useYouTubeEvent(player, 'autoplayBlocked', () => {
+    console.log('Autoplay was blocked');
+  });
 
-  const handleError = useCallback((error: YouTubeError) => {
-    console.error('플레이어 오류:', error);
-  }, []);
+  useYouTubeEvent(player, 'error', (error) => {
+    console.error('Player error:', error);
+    Alert.alert('Error', `Player error (${error.code}): ${error.message}`);
+  });
 
   return (
-    <YoutubePlayer
-      onReady={handleReady}
-      onStateChange={handleStateChange}
-      onError={handleError}
-      onPlaybackRateChange={handlePlaybackRateChange}
-      onPlaybackQualityChange={handlePlaybackQualityChange}
-      onAutoplayBlocked={handleAutoplayBlocked}
-    />
-  )
+    <YoutubeView player={player} />
+  );
 }
 ```
 
+`useYouTubeEvent` hook은 callback으로 값을 전달받는 방식과 state로 값을 바로 사용할 수 있는 두 가지 방법을 제공합니다.
+1. Callback 방식: 의존성에 따라 리렌더링이 필요한 경우 4번째 인자에 dependency array를 주입해주면 됩니다.
+2. State 방식:
+   1. `progress` event의 경우 3번째 인자에 interval 값을 설정할 수 있습니다. (기본값: 1000ms)
+   2. 나머지 event의 경우 3번째 인자에 기본 값을 설정할 수 있습니다.
+
 ### 기능
-YouTube iframe API의 [함수들](https://developers.google.com/youtube/iframe_api_reference#Functions)을 `ref`를 통해 호출하여 음소거, 재생, 볼륨 조절 등 다양한 플레이어 기능을 제어할 수 있습니다.   
+YouTube iframe API의 [함수들](https://developers.google.com/youtube/iframe_api_reference#Functions)을 `useYouTubePlayer`를 통해 반환된 player 인스턴스 메서드를 호출하여 음소거, 재생, 볼륨 조절 등 다양한 플레이어 기능을 제어할 수 있습니다.   
 
 ```tsx
+import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';
+
 function App() {
-  const playerRef = useRef<PlayerControls>(null);
+  const player = useYouTubePlayer(videoIdOrUrl);
 
   const [isPlaying, setIsPlaying] = useState(false);
   const [currentTime, setCurrentTime] = useState(0);
 
   const onPlay = useCallback(() => {
     if (isPlaying) {
-      playerRef.current?.pause();
+      player.pause();
       return;
     }
 
-    playerRef.current?.play();
+    player.play();
   }, [isPlaying]);
 
-  const seekTo = useCallback((time: number, allowSeekAhead: boolean) => {
-    playerRef.current?.seekTo(time, allowSeekAhead);
-  }, []);
+  const seekTo = (time: number, allowSeekAhead: boolean) => {
+    player.seekTo(time, allowSeekAhead);
+  };
 
-  const stop = () => playerRef.current?.stop();
+  const stop = () => player.stop();
 
   return (
     <View>
-      <YoutubePlayer
-        ref={playerRef}
-        source={source}
-      />
+      <YoutubeView player={player} />
 
       <View style={styles.controls}>
         <TouchableOpacity
@@ -161,23 +160,24 @@ function App() {
 }
 ```
 
-### 플레이어 매개변수
-YouTube 내장 플레이어의 [매개변수](https://developers.google.com/youtube/player_parameters#Parameters)를 설정하여 재생 환경을 맞춤화할 수 있습니다.
+### 초기 플레이어 매개변수
+YouTube 내장 플레이어의 [매개변수](https://developers.google.com/youtube/player_parameters#Parameters)를 설정하여 초기 재생 환경을 맞춤화할 수 있습니다.
 
 ```tsx
+import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';
+
 function App() {
+  const player = useYouTubePlayer(videoIdOrUrl, {
+    autoplay: true,
+    controls: true,
+    playsinline: true,
+    rel: false,
+    muted: true,
+  });
+
   return (
-    <YoutubePlayer
-      source={source}
-      playerVars={{
-        autoplay: true,
-        controls: true,
-        playsinline: true,
-        rel: false,
-        muted: true,
-      }}
-    />
-  )
+    <YoutubeView player={player} />
+  );
 }
 ```
 
@@ -187,8 +187,8 @@ YouTube 플레이어의 스타일을 원하는 대로 커스터마이징할 수
 ```tsx
 function App() {
   return (
-    <YoutubePlayer
-      source={source}
+    <YoutubeView
+      player={player}
       height={400}
       width={200}
       style={{
@@ -212,23 +212,20 @@ function App() {
 ```
 
 ### 재생 진행률 추적
-- `progressInterval`이 설정된 경우, 해당 간격(ms)마다 `onProgress` 콜백이 호출됩니다.
-- `progressInterval`이 `undefined`이거나 `0` 또는 `null`인 경우, `onProgress` 콜백은 호출되지 않습니다.
+- `useYouTubeEvent` hook을 사용하여 `progress` 이벤트의 리스너를 등록하여 재생 진행률을 추적할 수 있습니다.
+- 세 번째 인자에 interval 값을 설정하여 해당 간격(ms)마다 이벤트가 호출됩니다.
+- interval을 원치 않으면 `0`으로 설정하면 됩니다.
+- 기본값은 1000ms입니다.
 
 ```tsx
 function App() {
-  const handleProgress = useCallback((progress: ProgressData) => {
-    setCurrentTime(progress.currentTime);
-    setDuration(progress.duration);
-    setLoadedFraction(progress.loadedFraction);
-  }, []);
+  const progressInterval = 1000;
+
+  const player = useYouTubePlayer(videoIdOrUrl);
+  const progress = useYouTubeEvent(player, 'progress', progressInterval);
 
   return (
-    <YoutubePlayer
-      source={source}
-      progressInterval={1000}
-      onProgress={handleProgress}
-    />
+    <YoutubeView player={player} />
   )
 }
 ```
@@ -239,7 +236,9 @@ function App() {
 YouTube 플레이어 렌더링 방식을 제어하고 호환성을 위한 소스 URL을 설정합니다.
 
 1. **인라인 HTML 모드** (`useInlineHtml: true`)는 앱 내에서 직접 HTML을 로드하여 플레이어를 렌더링합니다. (default)
-2. **웹뷰 모드** (`useInlineHtml: false`)는 외부 플레이어 페이지를 로드합니다. 기본 URI는 https://react-native-youtube-bridge.pages.dev 입니다.
+2. **웹뷰 모드** (`useInlineHtml: false`)는 외부 플레이어 페이지를 로드합니다.
+   - 기본 URI는 https://react-native-youtube-bridge.pages.dev 입니다.
+   - 직접 제작한 커스텀 플레이어 페이지를 외부 웹뷰로 사용하려면, `@react-native-youtube-bridge/web`으로 플레이어를 구축한 후 `webViewUrl`에 해당 URL을 설정하세요. 자세한 구현 방법은 [웹 플레이어 가이드](https://github.com/react-native-bridges/react-native-youtube-bridge/tree/main/packages/web)를 참고해 주세요.
 
 > [!NOTE]
 > **webViewUrl 활용법**
@@ -250,14 +249,14 @@ YouTube 플레이어 렌더링 방식을 제어하고 호환성을 위한 소스
 
 ```tsx
 // 인라인 HTML (default)
-<YoutubePlayer
-  source={source}
+<YoutubeView
+  player={player}
   useInlineHtml
 />
 
 // 커스텀 플레이어 페이지를 사용한 외부 웹뷰
-<YoutubePlayer
-  source={source}
+<YoutubeView
+  player={player}
   useInlineHtml={false}
   // default: https://react-native-youtube-bridge.pages.dev
   webViewUrl="https://your-custom-player.com"
diff --git a/README.md b/README.md
index 1dcd602..2186645 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,9 @@
 
 > English | [한국어](./README-ko_kr.md)
 
+> [!note]
+> **V1 users:** [V1 Documentation](/packages/react-native-youtube-bridge/docs/v1.md) | [V2 Migration Guide](/packages/react-native-youtube-bridge/docs/migration-v2.md)
+
 ## Overview
 Using a YouTube player in React Native requires complex setup and configuration.   
 However, there are currently no actively maintained YouTube player libraries for React Native. (The most popular react-native-youtube-iframe's [latest release was July 2, 2023](https://github.com/LonelyCpp/react-native-youtube-iframe/releases/tag/v2.3.0))   
@@ -12,13 +15,15 @@ However, there are currently no actively maintained YouTube player libraries for
 - ✅ iOS, Android, and Web platform support
 - ✅ New Architecture support
 - ✅ Works without YouTube native player modules
-- ✅ [YouTube iframe Player API](https://developers.google.com/youtube/iframe_api_reference) feature support
-- ✅ Developer-friendly API
+- ✅ Support for various [YouTube iframe Player API](https://developers.google.com/youtube/iframe_api_reference) features
+- ✅ Multiple instance support - manage multiple players independently
+- ✅ Intuitive and easy-to-use Hook-based API very similar to Expo's approach
 - ✅ Expo support
-- ✅ Flexible rendering modes (Inline HTML & WebView)
+- ✅ Flexible rendering modes (inline HTML & webview)
+
+## Examples
 
-## Example
-> For a quick start, check out the [example](/example/).
+> If you want to get started quickly, check out the [example](/example/).
 
 - [Web Demo](https://react-native-youtube-bridge-example.pages.dev/)
 - [Expo Go](https://snack.expo.dev/@harang/react-native-youtube-bridge)
@@ -42,96 +47,94 @@ bun add react-native-youtube-bridge
 ## Usage
 
 ```tsx
-import { YoutubePlayer } from 'react-native-youtube-bridge';
+import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';
 
 function App() {
+  const videoIdOrUrl = 'AbZH7XWDW_k'
+
+  // OR useYouTubePlayer({ videoId: 'AbZH7XWDW_k' })
+  // OR useYouTubePlayer({ url: 'https://youtube.com/watch?v=AbZH7XWDW_k' })
+  const player = useYouTubePlayer(videoIdOrUrl);
+
   return (
-    <YoutubePlayer 
-      source={source} // youtube videoId or url
-      // OR source={{ videoId: 'AbZH7XWDW_k' }}
-      // OR source={{ url: 'https://youtube.com/watch?v=AbZH7XWDW_k' }}
-    />
-  )
+    <YoutubeView player={player} />
+  );
 }
 ```
 
 ### Events
-The library fires [events](https://developers.google.com/youtube/iframe_api_reference#Events) to notify your application of YouTube iframe API state changes. You can subscribe to these events using callback functions.   
 
-> 🔔 Note - Wrap callback functions with `useCallback` for performance optimization and to prevent abnormal behavior.
+[Events](https://developers.google.com/youtube/iframe_api_reference#Events) are fired to communicate YouTube iframe API state changes to your application.   
 
-```tsx
-function App() {
-  const playerRef = useRef<PlayerControls>(null);
+The `useYouTubeEvent` hook provides complete type inference and allows you to easily detect and use events in two ways.
 
-  const handleReady = useCallback(() => {
-    console.log('Player is ready!');
-  }, []);
+```tsx
+import { YoutubeView, useYouTubeEvent, useYouTubePlayer } from 'react-native-youtube-bridge';
 
-  const handleStateChange = useCallback((state: PlayerState) => {
-    console.log('Player state changed:', state);
-  }, []);
+function App() {
+  const player = useYouTubePlayer(videoIdOrUrl);
 
-  const handlePlaybackRateChange = useCallback((rate: number) => {
-    console.log('Playback rate changed:', rate);
-  }, []);
+  const playbackRate = useYouTubeEvent(player, 'playbackRateChange', 1);
+  const progress = useYouTubeEvent(player, 'progress', progressInterval);
 
-  const handlePlaybackQualityChange = useCallback((quality: string) => {
-    console.log('Playback quality changed:', quality);
-  }, []);
+  useYouTubeEvent(player, 'ready', (playerInfo) => {
+    console.log('Player is ready!');
+    Alert.alert('Alert', 'YouTube player is ready!');
+  });
 
-  const handleAutoplayBlocked = useCallback(() => {
+  useYouTubeEvent(player, 'autoplayBlocked', () => {
     console.log('Autoplay was blocked');
-  }, []);
+  });
 
-  const handleError = useCallback((error: YouTubeError) => {
+  useYouTubeEvent(player, 'error', (error) => {
     console.error('Player error:', error);
-  }, []);
+    Alert.alert('Error', `Player error (${error.code}): ${error.message}`);
+  });
 
   return (
-    <YoutubePlayer
-      onReady={handleReady}
-      onStateChange={handleStateChange}
-      onError={handleError}
-      onPlaybackRateChange={handlePlaybackRateChange}
-      onPlaybackQualityChange={handlePlaybackQualityChange}
-      onAutoplayBlocked={handleAutoplayBlocked}
-    />
-  )
+    <YoutubeView player={player} />
+  );
 }
 ```
 
-### Functions
-You can control various player features like mute, play, volume, and more by calling YouTube iframe API [functions](https://developers.google.com/youtube/iframe_api_reference#Functions) through the `ref`.   
+The `useYouTubeEvent` hook provides two ways to receive values: callback-based and state-based.
+
+1. **Callback method**: If re-rendering is needed based on dependencies, inject a dependency array as the 4th argument.
+2. **State method**:
+   1. For `progress` events, you can set an interval value as the 3rd argument. (default: 1000ms)
+   2. For other events, you can set a default value as the 3rd argument.
+
+### Features
+
+You can control various player features like muting, playing, and volume adjustment by calling methods on the player instance returned from `useYouTubePlayer`, which uses the YouTube iframe API [functions](https://developers.google.com/youtube/iframe_api_reference#Functions).   
 
 ```tsx
+import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';
+
 function App() {
-  const playerRef = useRef<PlayerControls>(null);
+  const player = useYouTubePlayer(videoIdOrUrl);
 
   const [isPlaying, setIsPlaying] = useState(false);
   const [currentTime, setCurrentTime] = useState(0);
 
   const onPlay = useCallback(() => {
     if (isPlaying) {
-      playerRef.current?.pause();
+      player.pause();
       return;
     }
 
-    playerRef.current?.play();
+    player.play();
   }, [isPlaying]);
 
-  const seekTo = useCallback((time: number, allowSeekAhead: boolean) => {
-    playerRef.current?.seekTo(time, allowSeekAhead);
-  }, []);
+  const seekTo = (time: number, allowSeekAhead: boolean) => {
+    player.seekTo(time, allowSeekAhead);
+  };
 
-  const stop = () => playerRef.current?.stop();
+  const stop = () => player.stop();
 
   return (
     <View>
-      <YoutubePlayer
-        ref={playerRef}
-        source={source}
-      />
+      <YoutubeView player={player} />
 
       <View style={styles.controls}>
         <TouchableOpacity
@@ -161,34 +164,37 @@ function App() {
 }
 ```
 
-### Player Parameters
-You can customize the playback environment by configuring YouTube embedded player [parameters](https://developers.google.com/youtube/player_parameters#Parameters).
+### Initial Player Parameters
+
+You can customize the initial playback environment by setting YouTube embedded player [parameters](https://developers.google.com/youtube/player_parameters#Parameters).
 
 ```tsx
+import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';
+
 function App() {
+  const player = useYouTubePlayer(videoIdOrUrl, {
+    autoplay: true,
+    controls: true,
+    playsinline: true,
+    rel: false,
+    muted: true,
+  });
+
   return (
-    <YoutubePlayer
-      source={source}
-      playerVars={{
-        autoplay: true,
-        controls: true,
-        playsinline: true,
-        rel: false,
-        muted: true,
-      }}
-    />
-  )
+    <YoutubeView player={player} />
+  );
 }
 ```
 
-### Styles
-You can customize the YouTube player's styling to match your application's design.
+### Styling
+
+You can customize the YouTube player's style as desired.
 
 ```tsx
 function App() {
   return (
-    <YoutubePlayer
-      source={source}
+    <YoutubeView
+      player={player}
       height={400}
       width={200}
       style={{
@@ -211,62 +217,62 @@ function App() {
 }
 ```
 
-### Playback Progress Tracking
-- If `progressInterval` is provided, the `onProgress` callback will be invoked at the specified interval (in milliseconds).
-- If `progressInterval` is `undefined`, `0`, or `null`, progress tracking is disabled and `onProgress` will not be called.
+### Tracking Playback Progress
+
+- You can track playback progress by registering a listener for the `progress` event using the `useYouTubeEvent` hook.
+- Set an interval value as the 3rd argument to have the event called at that interval (ms).
+- If you don't want an interval, set it to `0`.
+- The default value is 1000ms.
 
 ```tsx
 function App() {
-  const handleProgress = useCallback((progress: ProgressData) => {
-    setCurrentTime(progress.currentTime);
-    setDuration(progress.duration);
-    setLoadedFraction(progress.loadedFraction);
-  }, []);
+  const progressInterval = 1000;
+
+  const player = useYouTubePlayer(videoIdOrUrl);
+  const progress = useYouTubeEvent(player, 'progress', progressInterval);
 
   return (
-    <YoutubePlayer
-      source={source}
-      progressInterval={1000}
-      onProgress={handleProgress}
-    />
+    <YoutubeView player={player} />
   )
 }
 ```
 
-### Player Rendering & Source Configuration (ios, android)
+### Player Rendering and Source Configuration (iOS, Android)
 
 **Inline HTML vs WebView Mode**   
-Control YouTube player rendering method and configure source URLs for compatibility.
+Control the YouTube player rendering method and set source URLs for compatibility.
 
-1. **Inline HTML Mode** (`useInlineHtml: true`) renders the player by loading HTML directly within the app. (default)
-2. **WebView Mode** (`useInlineHtml: false`) loads an external player page. The default URI is https://react-native-youtube-bridge.pages.dev.
+1. **Inline HTML mode** (`useInlineHtml: true`) renders the player by loading HTML directly within the app. (default)
+2. **WebView mode** (`useInlineHtml: false`) loads an external player page. 
+   - The default URI is https://react-native-youtube-bridge.pages.dev.
+   - To use your own custom player page as an external WebView, build your player with `@react-native-youtube-bridge/web` and set the URL in the `webViewUrl` property. For detailed implementation instructions, please refer to the [Web Player Guide](https://github.com/react-native-bridges/react-native-youtube-bridge/tree/main/packages/web).
 
 > [!NOTE]
 > **webViewUrl Usage**
-> - When `useInlineHtml: true`: Set as the `baseUrl` for WebView source HTML.
-> - When `useInlineHtml: false`: Overrides the WebView source `uri`.
+> - When `useInlineHtml: true`: Set as the HTML `baseUrl` of the WebView source.
+> - When `useInlineHtml: false`: Overrides the WebView source's `uri`.
 >
-> **Embed Restriction Solution**: If you encounter `embed not allowed` errors with YouTube iframe when using inline HTML mode and videos don't load properly, switch to WebView mode to load YouTube iframe through an external player.
+> **Resolving Embed Restrictions**: If you encounter `embed not allowed` errors from the YouTube iframe when using inline HTML and the video doesn't load properly, switch to WebView mode to load the YouTube iframe through an external player.
 
 ```tsx
 // Inline HTML (default)
-<YoutubePlayer
- source={source}
- useInlineHtml
+<YoutubeView
+  player={player}
+  useInlineHtml
 />
 
-// External WebView with custom player page
-<YoutubePlayer
- source={source}
- useInlineHtml={false}
- // default: https://react-native-youtube-bridge.pages.dev
- webViewUrl="https://your-custom-player.com"
+// External WebView using custom player page
+<YoutubeView
+  player={player}
+  useInlineHtml={false}
+  // default: https://react-native-youtube-bridge.pages.dev
+  webViewUrl="https://your-custom-player.com"
 />
 ```
 
 **Custom Player Page**
 
-To use your own custom player page, you can build a React-based player using `@react-native-youtube-bridge/web`.
+To use a custom player page you've created, you can build a React-based player page using `@react-native-youtube-bridge/web`.
 
 ```tsx
 import { YoutubePlayer } from '@react-native-youtube-bridge/web';
@@ -281,28 +287,29 @@ export default CustomPlayerPage;
 > For more details, please refer to the [Web Player Guide](./packages/web/).
 
 ### YouTube oEmbed API
-Use the `useYoutubeOEmbed` hook to fetch YouTube video metadata.  
+
+You can fetch YouTube video metadata through the `useYoutubeOEmbed` hook.   
 This hook only supports YouTube URLs.
 
 ```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 <Text>Loading...</Text>;
- if (error) return <Text>Error: {error.message}</Text>;
- if (!oEmbed) return null;
-
- return (
-   <>
-     <Text>{oEmbed.title}</Text>
-     <Image 
-       source={{ uri: oEmbed?.thumbnail_url }} 
-       style={{ width: oEmbed?.thumbnail_width, height: oEmbed?.thumbnail_height }} 
-     />
-   </>
- )
+  const { oEmbed, isLoading, error } = useYoutubeOEmbed('https://www.youtube.com/watch?v=AbZH7XWDW_k');
+
+  if (isLoading) return <Text>Loading...</Text>;
+  if (error) return <Text>Error: {error.message}</Text>;
+  if (!oEmbed) return null;
+
+  return (
+    <>
+      <Text>{oEmbed.title}</Text>
+      <Image 
+        source={{ uri: oEmbed?.thumbnail_url }} 
+        style={{ width: oEmbed?.thumbnail_width, height: oEmbed?.thumbnail_height }} 
+      />
+    </>
+  )
 }
 ```
 
diff --git a/packages/react-native-youtube-bridge/README-ko_kr.md b/packages/react-native-youtube-bridge/README-ko_kr.md
index 062a9ef..fb98b4a 100644
--- a/packages/react-native-youtube-bridge/README-ko_kr.md
+++ b/packages/react-native-youtube-bridge/README-ko_kr.md
@@ -2,6 +2,9 @@
 
 > [English](./README.md) | 한국어
 
+> [!note]
+> **V1 사용자:** [V1 문서](/packages/react-native-youtube-bridge/docs/v1.md) | [V2 마이그레이션 가이드](/packages/react-native-youtube-bridge/docs/migration-v2.md)
+
 ## 개요
 React Native에서 YouTube 플레이어를 사용하려면 복잡한 설정이 필요합니다.   
 하지만 현재 지속적으로 유지보수되고 있는 React Native용 YouTube 플레이어 라이브러리가 없는 상황입니다. (가장 인기 있는 react-native-youtube-iframe의 [최근 릴리즈는 2023년 07월 02일](https://github.com/LonelyCpp/react-native-youtube-iframe/releases/tag/v2.3.0))   
@@ -13,7 +16,8 @@ React Native에서 YouTube 플레이어를 사용하려면 복잡한 설정이 
 - ✅ New Architecture 지원
 - ✅ YouTube 네이티브 플레이어 모듈 없이도 사용 가능
 - ✅ 다양한 [YouTube iframe Player API](https://developers.google.com/youtube/iframe_api_reference) 기능 지원
-- ✅ 개발자 친화적인 API 제공
+- ✅ 다중 인스턴스 지원 - 여러 플레이어를 독립적으로 관리 가능
+- ✅ Expo의 접근 방식과 매우 유사한 직관적이고 사용하기 쉬운 Hook 기반 API 제공
 - ✅ Expo 지원
 - ✅ 유연한 렌더링 모드 (인라인 HTML & 웹뷰)
 
@@ -42,96 +46,91 @@ bun add react-native-youtube-bridge
 ## 사용법
 
 ```tsx
-import { YoutubePlayer } from 'react-native-youtube-bridge';
+import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';
 
 function App() {
+  const videoIdOrUrl = 'AbZH7XWDW_k'
+
+  // OR useYouTubePlayer({ videoId: 'AbZH7XWDW_k' })
+  // OR useYouTubePlayer({ url: 'https://youtube.com/watch?v=AbZH7XWDW_k' })
+  const player = useYouTubePlayer(videoIdOrUrl);
+
   return (
-    <YoutubePlayer 
-      source={source} // youtube videoId or url
-      // OR source={{ videoId: 'AbZH7XWDW_k' }}
-      // OR source={{ url: 'https://youtube.com/watch?v=AbZH7XWDW_k' }}
-    />
-  )
+    <YoutubeView player={player} />
+  );
 }
 ```
 
 ### 이벤트
-YouTube iframe API의 상태 변화를 애플리케이션에 전달하기 위해 [이벤트](https://developers.google.com/youtube/iframe_api_reference#Events)를 발생시킵니다. 콜백 함수를 통해 원하는 이벤트를 구독할 수 있습니다.   
+YouTube iframe API의 상태 변화를 애플리케이션에 전달하기 위해 [이벤트](https://developers.google.com/youtube/iframe_api_reference#Events)를 발생시킵니다.   
 
-> 🔔 Note - 성능 최적화 및 비정상 동작 방지를 위해 콜백 함수는 `useCallback`으로 감싸주세요.
+`useYouTubeEvent` hook을 사용하여 완벽한 타입 추론을 지원하며, 두 가지 방법으로 이벤트를 쉽게 감지하여 사용할 수 있습니다.
 
 ```tsx
-function App() {
-  const playerRef = useRef<PlayerControls>(null);
-
-  const handleReady = useCallback(() => {
-    console.log('플레이어 준비 완료!');
-  }, []);
+import { YoutubeView, useYouTubeEvent, useYouTubePlayer } from 'react-native-youtube-bridge';
 
-  const handleStateChange = useCallback((state: PlayerState) => {
-    console.log('플레이어 상태 변경:', state);
-  }, []);
+function App() {
+  const player = useYouTubePlayer(videoIdOrUrl);
 
-  const handlePlaybackRateChange = useCallback((rate: number) => {
-    console.log('재생 속도 변경:', rate);
-  }, []);
+  const playbackRate = useYouTubeEvent(player, 'playbackRateChange', 1);
+  const progress = useYouTubeEvent(player, 'progress', progressInterval);
 
-  const handlePlaybackQualityChange = useCallback((quality: string) => {
-    console.log('재생 품질 변경:', quality);
-  }, []);
+  useYouTubeEvent(player, 'ready', (playerInfo) => {
+    console.log('Player is ready!');
+    Alert.alert('Alert', 'YouTube player is ready!');
+  });
 
-  const handleAutoplayBlocked = useCallback(() => {
-    console.log('자동 재생이 차단되었습니다');
-  }, []);
+  useYouTubeEvent(player, 'autoplayBlocked', () => {
+    console.log('Autoplay was blocked');
+  });
 
-  const handleError = useCallback((error: YouTubeError) => {
-    console.error('플레이어 오류:', error);
-  }, []);
+  useYouTubeEvent(player, 'error', (error) => {
+    console.error('Player error:', error);
+    Alert.alert('Error', `Player error (${error.code}): ${error.message}`);
+  });
 
   return (
-    <YoutubePlayer
-      onReady={handleReady}
-      onStateChange={handleStateChange}
-      onError={handleError}
-      onPlaybackRateChange={handlePlaybackRateChange}
-      onPlaybackQualityChange={handlePlaybackQualityChange}
-      onAutoplayBlocked={handleAutoplayBlocked}
-    />
-  )
+    <YoutubeView player={player} />
+  );
 }
 ```
 
+`useYouTubeEvent` hook은 callback으로 값을 전달받는 방식과 state로 값을 바로 사용할 수 있는 두 가지 방법을 제공합니다.
+1. Callback 방식: 의존성에 따라 리렌더링이 필요한 경우 4번째 인자에 dependency array를 주입해주면 됩니다.
+2. State 방식:
+   1. `progress` event의 경우 3번째 인자에 interval 값을 설정할 수 있습니다. (기본값: 1000ms)
+   2. 나머지 event의 경우 3번째 인자에 기본 값을 설정할 수 있습니다.
+
 ### 기능
-YouTube iframe API의 [함수들](https://developers.google.com/youtube/iframe_api_reference#Functions)을 `ref`를 통해 호출하여 음소거, 재생, 볼륨 조절 등 다양한 플레이어 기능을 제어할 수 있습니다.   
+YouTube iframe API의 [함수들](https://developers.google.com/youtube/iframe_api_reference#Functions)을 `useYouTubePlayer`를 통해 반환된 player 인스턴스 메서드를 호출하여 음소거, 재생, 볼륨 조절 등 다양한 플레이어 기능을 제어할 수 있습니다.   
 
 ```tsx
+import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';
+
 function App() {
-  const playerRef = useRef<PlayerControls>(null);
+  const player = useYouTubePlayer(videoIdOrUrl);
 
   const [isPlaying, setIsPlaying] = useState(false);
   const [currentTime, setCurrentTime] = useState(0);
 
   const onPlay = useCallback(() => {
     if (isPlaying) {
-      playerRef.current?.pause();
+      player.pause();
       return;
     }
 
-    playerRef.current?.play();
+    player.play();
   }, [isPlaying]);
 
-  const seekTo = useCallback((time: number, allowSeekAhead: boolean) => {
-    playerRef.current?.seekTo(time, allowSeekAhead);
-  }, []);
+  const seekTo = (time: number, allowSeekAhead: boolean) => {
+    player.seekTo(time, allowSeekAhead);
+  };
 
-  const stop = () => playerRef.current?.stop();
+  const stop = () => player.stop();
 
   return (
     <View>
-      <YoutubePlayer
-        ref={playerRef}
-        source={source}
-      />
+      <YoutubeView player={player} />
 
       <View style={styles.controls}>
         <TouchableOpacity
@@ -161,23 +160,24 @@ function App() {
 }
 ```
 
-### 플레이어 매개변수
-YouTube 내장 플레이어의 [매개변수](https://developers.google.com/youtube/player_parameters#Parameters)를 설정하여 재생 환경을 맞춤화할 수 있습니다.
+### 초기 플레이어 매개변수
+YouTube 내장 플레이어의 [매개변수](https://developers.google.com/youtube/player_parameters#Parameters)를 설정하여 초기 재생 환경을 맞춤화할 수 있습니다.
 
 ```tsx
+import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';
+
 function App() {
+  const player = useYouTubePlayer(videoIdOrUrl, {
+    autoplay: true,
+    controls: true,
+    playsinline: true,
+    rel: false,
+    muted: true,
+  });
+
   return (
-    <YoutubePlayer
-      source={source}
-      playerVars={{
-        autoplay: true,
-        controls: true,
-        playsinline: true,
-        rel: false,
-        muted: true,
-      }}
-    />
-  )
+    <YoutubeView player={player} />
+  );
 }
 ```
 
@@ -187,8 +187,8 @@ YouTube 플레이어의 스타일을 원하는 대로 커스터마이징할 수
 ```tsx
 function App() {
   return (
-    <YoutubePlayer
-      source={source}
+    <YoutubeView
+      player={player}
       height={400}
       width={200}
       style={{
@@ -212,23 +212,20 @@ function App() {
 ```
 
 ### 재생 진행률 추적
-- `progressInterval`이 설정된 경우, 해당 간격(ms)마다 `onProgress` 콜백이 호출됩니다.
-- `progressInterval`이 `undefined`이거나 `0` 또는 `null`인 경우, `onProgress` 콜백은 호출되지 않습니다.
+- `useYouTubeEvent` hook을 사용하여 `progress` 이벤트의 리스너를 등록하여 재생 진행률을 추적할 수 있습니다.
+- 세 번째 인자에 interval 값을 설정하여 해당 간격(ms)마다 이벤트가 호출됩니다.
+- interval을 원치 않으면 `0`으로 설정하면 됩니다.
+- 기본값은 1000ms입니다.
 
 ```tsx
 function App() {
-  const handleProgress = useCallback((progress: ProgressData) => {
-    setCurrentTime(progress.currentTime);
-    setDuration(progress.duration);
-    setLoadedFraction(progress.loadedFraction);
-  }, []);
+  const progressInterval = 1000;
+
+  const player = useYouTubePlayer(videoIdOrUrl);
+  const progress = useYouTubeEvent(player, 'progress', progressInterval);
 
   return (
-    <YoutubePlayer
-      source={source}
-      progressInterval={1000}
-      onProgress={handleProgress}
-    />
+    <YoutubeView player={player} />
   )
 }
 ```
@@ -252,14 +249,14 @@ YouTube 플레이어 렌더링 방식을 제어하고 호환성을 위한 소스
 
 ```tsx
 // 인라인 HTML (default)
-<YoutubePlayer
-  source={source}
+<YoutubeView
+  player={player}
   useInlineHtml
 />
 
 // 커스텀 플레이어 페이지를 사용한 외부 웹뷰
-<YoutubePlayer
-  source={source}
+<YoutubeView
+  player={player}
   useInlineHtml={false}
   // default: https://react-native-youtube-bridge.pages.dev
   webViewUrl="https://your-custom-player.com"
diff --git a/packages/react-native-youtube-bridge/README.md b/packages/react-native-youtube-bridge/README.md
index 88eac96..652214a 100644
--- a/packages/react-native-youtube-bridge/README.md
+++ b/packages/react-native-youtube-bridge/README.md
@@ -2,6 +2,9 @@
 
 > English | [한국어](./README-ko_kr.md)
 
+> [!note]
+> **V1 users:** [V1 Documentation](/packages/react-native-youtube-bridge/docs/v1.md) | [V2 Migration Guide](/packages/react-native-youtube-bridge/docs/migration-v2.md)
+
 ## Overview
 Using a YouTube player in React Native requires complex setup and configuration.   
 However, there are currently no actively maintained YouTube player libraries for React Native. (The most popular react-native-youtube-iframe's [latest release was July 2, 2023](https://github.com/LonelyCpp/react-native-youtube-iframe/releases/tag/v2.3.0))   
@@ -12,13 +15,15 @@ However, there are currently no actively maintained YouTube player libraries for
 - ✅ iOS, Android, and Web platform support
 - ✅ New Architecture support
 - ✅ Works without YouTube native player modules
-- ✅ [YouTube iframe Player API](https://developers.google.com/youtube/iframe_api_reference) feature support
-- ✅ Developer-friendly API
+- ✅ Support for various [YouTube iframe Player API](https://developers.google.com/youtube/iframe_api_reference) features
+- ✅ Multiple instance support - manage multiple players independently
+- ✅ Intuitive and easy-to-use Hook-based API very similar to Expo's approach
 - ✅ Expo support
-- ✅ Flexible rendering modes (Inline HTML & WebView)
+- ✅ Flexible rendering modes (inline HTML & webview)
+
+## Examples
 
-## Example
-> For a quick start, check out the [example](/example/).
+> If you want to get started quickly, check out the [example](/example/).
 
 - [Web Demo](https://react-native-youtube-bridge-example.pages.dev/)
 - [Expo Go](https://snack.expo.dev/@harang/react-native-youtube-bridge)
@@ -42,96 +47,94 @@ bun add react-native-youtube-bridge
 ## Usage
 
 ```tsx
-import { YoutubePlayer } from 'react-native-youtube-bridge';
+import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';
 
 function App() {
+  const videoIdOrUrl = 'AbZH7XWDW_k'
+
+  // OR useYouTubePlayer({ videoId: 'AbZH7XWDW_k' })
+  // OR useYouTubePlayer({ url: 'https://youtube.com/watch?v=AbZH7XWDW_k' })
+  const player = useYouTubePlayer(videoIdOrUrl);
+
   return (
-    <YoutubePlayer 
-      source={source} // youtube videoId or url
-      // OR source={{ videoId: 'AbZH7XWDW_k' }}
-      // OR source={{ url: 'https://youtube.com/watch?v=AbZH7XWDW_k' }}
-    />
-  )
+    <YoutubeView player={player} />
+  );
 }
 ```
 
 ### Events
-The library fires [events](https://developers.google.com/youtube/iframe_api_reference#Events) to notify your application of YouTube iframe API state changes. You can subscribe to these events using callback functions.   
 
-> 🔔 Note - Wrap callback functions with `useCallback` for performance optimization and to prevent abnormal behavior.
+[Events](https://developers.google.com/youtube/iframe_api_reference#Events) are fired to communicate YouTube iframe API state changes to your application.   
 
-```tsx
-function App() {
-  const playerRef = useRef<PlayerControls>(null);
+The `useYouTubeEvent` hook provides complete type inference and allows you to easily detect and use events in two ways.
 
-  const handleReady = useCallback(() => {
-    console.log('Player is ready!');
-  }, []);
+```tsx
+import { YoutubeView, useYouTubeEvent, useYouTubePlayer } from 'react-native-youtube-bridge';
 
-  const handleStateChange = useCallback((state: PlayerState) => {
-    console.log('Player state changed:', state);
-  }, []);
+function App() {
+  const player = useYouTubePlayer(videoIdOrUrl);
 
-  const handlePlaybackRateChange = useCallback((rate: number) => {
-    console.log('Playback rate changed:', rate);
-  }, []);
+  const playbackRate = useYouTubeEvent(player, 'playbackRateChange', 1);
+  const progress = useYouTubeEvent(player, 'progress', progressInterval);
 
-  const handlePlaybackQualityChange = useCallback((quality: string) => {
-    console.log('Playback quality changed:', quality);
-  }, []);
+  useYouTubeEvent(player, 'ready', (playerInfo) => {
+    console.log('Player is ready!');
+    Alert.alert('Alert', 'YouTube player is ready!');
+  });
 
-  const handleAutoplayBlocked = useCallback(() => {
+  useYouTubeEvent(player, 'autoplayBlocked', () => {
     console.log('Autoplay was blocked');
-  }, []);
+  });
 
-  const handleError = useCallback((error: YouTubeError) => {
+  useYouTubeEvent(player, 'error', (error) => {
     console.error('Player error:', error);
-  }, []);
+    Alert.alert('Error', `Player error (${error.code}): ${error.message}`);
+  });
 
   return (
-    <YoutubePlayer
-      onReady={handleReady}
-      onStateChange={handleStateChange}
-      onError={handleError}
-      onPlaybackRateChange={handlePlaybackRateChange}
-      onPlaybackQualityChange={handlePlaybackQualityChange}
-      onAutoplayBlocked={handleAutoplayBlocked}
-    />
-  )
+    <YoutubeView player={player} />
+  );
 }
 ```
 
-### Functions
-You can control various player features like mute, play, volume, and more by calling YouTube iframe API [functions](https://developers.google.com/youtube/iframe_api_reference#Functions) through the `ref`.   
+The `useYouTubeEvent` hook provides two ways to receive values: callback-based and state-based.
+
+1. **Callback method**: If re-rendering is needed based on dependencies, inject a dependency array as the 4th argument.
+2. **State method**:
+   1. For `progress` events, you can set an interval value as the 3rd argument. (default: 1000ms)
+   2. For other events, you can set a default value as the 3rd argument.
+
+### Features
+
+You can control various player features like muting, playing, and volume adjustment by calling methods on the player instance returned from `useYouTubePlayer`, which uses the YouTube iframe API [functions](https://developers.google.com/youtube/iframe_api_reference#Functions).   
 
 ```tsx
+import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';
+
 function App() {
-  const playerRef = useRef<PlayerControls>(null);
+  const player = useYouTubePlayer(videoIdOrUrl);
 
   const [isPlaying, setIsPlaying] = useState(false);
   const [currentTime, setCurrentTime] = useState(0);
 
   const onPlay = useCallback(() => {
     if (isPlaying) {
-      playerRef.current?.pause();
+      player.pause();
       return;
     }
 
-    playerRef.current?.play();
+    player.play();
   }, [isPlaying]);
 
-  const seekTo = useCallback((time: number, allowSeekAhead: boolean) => {
-    playerRef.current?.seekTo(time, allowSeekAhead);
-  }, []);
+  const seekTo = (time: number, allowSeekAhead: boolean) => {
+    player.seekTo(time, allowSeekAhead);
+  };
 
-  const stop = () => playerRef.current?.stop();
+  const stop = () => player.stop();
 
   return (
     <View>
-      <YoutubePlayer
-        ref={playerRef}
-        source={source}
-      />
+      <YoutubeView player={player} />
 
       <View style={styles.controls}>
         <TouchableOpacity
@@ -161,34 +164,37 @@ function App() {
 }
 ```
 
-### Player Parameters
-You can customize the playback environment by configuring YouTube embedded player [parameters](https://developers.google.com/youtube/player_parameters#Parameters).
+### Initial Player Parameters
+
+You can customize the initial playback environment by setting YouTube embedded player [parameters](https://developers.google.com/youtube/player_parameters#Parameters).
 
 ```tsx
+import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';
+
 function App() {
+  const player = useYouTubePlayer(videoIdOrUrl, {
+    autoplay: true,
+    controls: true,
+    playsinline: true,
+    rel: false,
+    muted: true,
+  });
+
   return (
-    <YoutubePlayer
-      source={source}
-      playerVars={{
-        autoplay: true,
-        controls: true,
-        playsinline: true,
-        rel: false,
-        muted: true,
-      }}
-    />
-  )
+    <YoutubeView player={player} />
+  );
 }
 ```
 
-### Styles
-You can customize the YouTube player's styling to match your application's design.
+### Styling
+
+You can customize the YouTube player's style as desired.
 
 ```tsx
 function App() {
   return (
-    <YoutubePlayer
-      source={source}
+    <YoutubeView
+      player={player}
       height={400}
       width={200}
       style={{
@@ -211,64 +217,62 @@ function App() {
 }
 ```
 
-### Playback Progress Tracking
-- If `progressInterval` is provided, the `onProgress` callback will be invoked at the specified interval (in milliseconds).
-- If `progressInterval` is `undefined`, `0`, or `null`, progress tracking is disabled and `onProgress` will not be called.
+### Tracking Playback Progress
+
+- You can track playback progress by registering a listener for the `progress` event using the `useYouTubeEvent` hook.
+- Set an interval value as the 3rd argument to have the event called at that interval (ms).
+- If you don't want an interval, set it to `0`.
+- The default value is 1000ms.
 
 ```tsx
 function App() {
-  const handleProgress = useCallback((progress: ProgressData) => {
-    setCurrentTime(progress.currentTime);
-    setDuration(progress.duration);
-    setLoadedFraction(progress.loadedFraction);
-  }, []);
+  const progressInterval = 1000;
+
+  const player = useYouTubePlayer(videoIdOrUrl);
+  const progress = useYouTubeEvent(player, 'progress', progressInterval);
 
   return (
-    <YoutubePlayer
-      source={source}
-      progressInterval={1000}
-      onProgress={handleProgress}
-    />
+    <YoutubeView player={player} />
   )
 }
 ```
 
-### Player Rendering & Source Configuration (ios, android)
+### Player Rendering and Source Configuration (iOS, Android)
 
 **Inline HTML vs WebView Mode**   
-Control YouTube player rendering method and configure source URLs for compatibility.
+Control the YouTube player rendering method and set source URLs for compatibility.
 
-1. **Inline HTML Mode** (`useInlineHtml: true`) renders the player by loading HTML directly within the app. (default)
-2. **WebView Mode** (`useInlineHtml: false`) loads an external player page.
+1. **Inline HTML mode** (`useInlineHtml: true`) renders the player by loading HTML directly within the app. (default)
+2. **WebView mode** (`useInlineHtml: false`) loads an external player page. 
    - The default URI is https://react-native-youtube-bridge.pages.dev.
    - To use your own custom player page as an external WebView, build your player with `@react-native-youtube-bridge/web` and set the URL in the `webViewUrl` property. For detailed implementation instructions, please refer to the [Web Player Guide](https://github.com/react-native-bridges/react-native-youtube-bridge/tree/main/packages/web).
 
 > [!NOTE]
 > **webViewUrl Usage**
-> - When `useInlineHtml: true`: Set as the `baseUrl` for WebView source HTML.
-> - When `useInlineHtml: false`: Overrides the WebView source `uri`.
+> - When `useInlineHtml: true`: Set as the HTML `baseUrl` of the WebView source.
+> - When `useInlineHtml: false`: Overrides the WebView source's `uri`.
 >
-> **Embed Restriction Solution**: If you encounter `embed not allowed` errors with YouTube iframe when using inline HTML mode and videos don't load properly, switch to WebView mode to load YouTube iframe through an external player.
+> **Resolving Embed Restrictions**: If you encounter `embed not allowed` errors from the YouTube iframe when using inline HTML and the video doesn't load properly, switch to WebView mode to load the YouTube iframe through an external player.
 
 ```tsx
 // Inline HTML (default)
-<YoutubePlayer
- source={source}
- useInlineHtml
+<YoutubeView
+  player={player}
+  useInlineHtml
 />
 
-// External WebView with custom player page
-<YoutubePlayer
- source={source}
- useInlineHtml={false}
- // default: https://react-native-youtube-bridge.pages.dev
- webViewUrl="https://your-custom-player.com"
+// External WebView using custom player page
+<YoutubeView
+  player={player}
+  useInlineHtml={false}
+  // default: https://react-native-youtube-bridge.pages.dev
+  webViewUrl="https://your-custom-player.com"
 />
 ```
 
 **Custom Player Page**
 
-To use your own custom player page, you can build a React-based player using `@react-native-youtube-bridge/web`.
+To use a custom player page you've created, you can build a React-based player page using `@react-native-youtube-bridge/web`.
 
 ```tsx
 import { YoutubePlayer } from '@react-native-youtube-bridge/web';
@@ -283,28 +287,29 @@ export default CustomPlayerPage;
 > For more details, please refer to the [Web Player Guide](https://github.com/react-native-bridges/react-native-youtube-bridge/tree/main/packages/web).
 
 ### YouTube oEmbed API
-Use the `useYoutubeOEmbed` hook to fetch YouTube video metadata.  
+
+You can fetch YouTube video metadata through the `useYoutubeOEmbed` hook.   
 This hook only supports YouTube URLs.
 
 ```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 <Text>Loading...</Text>;
- if (error) return <Text>Error: {error.message}</Text>;
- if (!oEmbed) return null;
-
- return (
-   <>
-     <Text>{oEmbed.title}</Text>
-     <Image 
-       source={{ uri: oEmbed?.thumbnail_url }} 
-       style={{ width: oEmbed?.thumbnail_width, height: oEmbed?.thumbnail_height }} 
-     />
-   </>
- )
+  const { oEmbed, isLoading, error } = useYoutubeOEmbed('https://www.youtube.com/watch?v=AbZH7XWDW_k');
+
+  if (isLoading) return <Text>Loading...</Text>;
+  if (error) return <Text>Error: {error.message}</Text>;
+  if (!oEmbed) return null;
+
+  return (
+    <>
+      <Text>{oEmbed.title}</Text>
+      <Image 
+        source={{ uri: oEmbed?.thumbnail_url }} 
+        style={{ width: oEmbed?.thumbnail_width, height: oEmbed?.thumbnail_height }} 
+      />
+    </>
+  )
 }
 ```
 
diff --git a/packages/react-native-youtube-bridge/docs/migration-v2.md b/packages/react-native-youtube-bridge/docs/migration-v2.md
new file mode 100644
index 0000000..e69453a
--- /dev/null
+++ b/packages/react-native-youtube-bridge/docs/migration-v2.md
@@ -0,0 +1,231 @@
+# Migration Guide: v1 to v2
+
+This guide will help you migrate from react-native-youtube-bridge v1 to v2. The v2 API is completely redesigned to be more React-friendly using hooks, similar to expo-audio and expo-video.
+
+## Overview of Changes
+
+| Aspect | v1 (Old) | v2 (New) |
+|--------|----------|----------|
+| **API Style** | Imperative (ref-based) | Declarative (hooks-based) |
+| **Component** | `YoutubePlayer` | `YoutubeView` + `useYouTubePlayer` |
+| **Event Handling** | Manual listeners + props | `useYouTubeEvent` hook |
+| **State Management** | Manual `useState` | Automatic reactive updates |
+| **Player Control** | `playerRef.current.method()` | `player.method()` |
+| **Configuration** | Component props | Hook parameters |
+
+## Step-by-Step Migration
+
+### 1. Component Replacement
+
+**Before (v1):**
+```jsx
+import { YoutubePlayer } from 'react-native-youtube-bridge';
+
+<YoutubePlayer
+  ref={playerRef}
+  source={videoId}
+  height={400}
+  playerVars={{
+    autoplay: true,
+    controls: true,
+    playsinline: true,
+    rel: false,
+    muted: true,
+  }}
+  onReady={handleReady}
+  onStateChange={handleStateChange}
+  onProgress={handleProgress}
+  onError={handleError}
+/>
+```
+
+**After (v2):**
+```jsx
+import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';
+
+const player = useYouTubePlayer(videoId, {
+  autoplay: true,
+  controls: true,
+  playsinline: true,
+  rel: false,
+  muted: true,
+});
+
+<YoutubeView
+  player={player}
+  style={{ height: 400 }}
+/>
+```
+
+### 2. Event Handling Migration
+
+The `useYouTubeEvent` hook provides complete type inference and allows you to handle events in two ways: **callback-based** and **state-based**.
+
+**Before (v1):**
+```jsx
+// Manual event handlers and state management
+const [isPlaying, setIsPlaying] = useState(false);
+const [currentTime, setCurrentTime] = useState(0);
+const [duration, setDuration] = useState(0);
+const [playbackRate, setPlaybackRate] = useState(1);
+const [availableRates, setAvailableRates] = useState([1]);
+
+const handleReady = useCallback((playerInfo) => {
+  console.log('Player is ready!');
+  if (playerInfo?.availablePlaybackRates) {
+    setAvailableRates(playerInfo.availablePlaybackRates);
+  }
+}, []);
+
+const handleStateChange = useCallback((state) => {
+  setIsPlaying(state === PlayerState.PLAYING);
+}, []);
+
+const handleProgress = useCallback((progress) => {
+  setCurrentTime(progress.currentTime);
+  setDuration(progress.duration);
+}, []);
+
+const handlePlaybackRateChange = useCallback((rate) => {
+  setPlaybackRate(rate);
+}, []);
+```
+
+**After (v2):**
+```jsx
+// State-based event handling (reactive values)
+const playbackRate = useYouTubeEvent(player, 'playbackRateChange', 1);
+const progress = useYouTubeEvent(player, 'progress', 1000); // 1000ms interval
+const state = useYouTubeEvent(player, 'stateChange');
+
+const currentTime = progress?.currentTime ?? 0;
+const duration = progress?.duration ?? 0;
+const isPlaying = state === PlayerState.PLAYING;
+
+// Callback-based event handling (for side effects)
+const [availableRates, setAvailableRates] = useState([1]);
+
+useYouTubeEvent(player, 'ready', (playerInfo) => {
+  console.log('Player is ready!');
+  if (playerInfo?.availablePlaybackRates) {
+    setAvailableRates(playerInfo.availablePlaybackRates);
+  }
+});
+
+useYouTubeEvent(player, 'autoplayBlocked', () => {
+  console.log('Autoplay was blocked');
+});
+
+useYouTubeEvent(player, 'error', (error) => {
+  console.error('Player error:', error);
+  Alert.alert('Error', `Player error (${error.code}): ${error.message}`);
+});
+```
+
+#### `useYouTubeEvent` Usage Patterns:
+
+1. **State method** - Returns reactive values:
+   ```jsx
+   // For progress events with custom interval
+   const progress = useYouTubeEvent(player, 'progress', 1000); // 1000ms interval
+   
+   // For other events with default value
+   const playbackRate = useYouTubeEvent(player, 'playbackRateChange', 1);
+   const state = useYouTubeEvent(player, 'stateChange');
+   ```
+
+2. **Callback method** - For side effects and actions:
+   ```jsx
+   // Simple callback
+   useYouTubeEvent(player, 'ready', (playerInfo) => {
+     console.log('Player ready:', playerInfo);
+   });
+   
+   // With dependency array for re-rendering control
+   useYouTubeEvent(player, 'stateChange', (state) => {
+     // Handle state change
+   }, [/* dependencies */]);
+   ```
+
+### 3. Player Control Migration
+
+**Before (v1):**
+```jsx
+const playerRef = useRef<PlayerControls>(null);
+
+// Player methods
+const play = () => playerRef.current?.play();
+const pause = () => playerRef.current?.pause();
+const stop = () => playerRef.current?.stop();
+const seekTo = (time) => playerRef.current?.seekTo(time);
+const setVolume = (volume) => playerRef.current?.setVolume(volume);
+const mute = () => playerRef.current?.mute();
+const unMute = () => playerRef.current?.unMute();
+
+// Getting player info
+const getPlayerInfo = async () => {
+  const currentTime = await playerRef.current?.getCurrentTime();
+  const duration = await playerRef.current?.getDuration();
+  const state = await playerRef.current?.getPlayerState();
+};
+```
+
+**After (v2):**
+```jsx
+const player = useYouTubePlayer(videoId, config);
+
+// Player methods (direct calls)
+const play = () => player.play();
+const pause = () => player.pause();
+const stop = () => player.stop();
+const seekTo = (time) => player.seekTo(time);
+const setVolume = (volume) => player.setVolume(volume);
+const mute = () => player.mute();
+const unMute = () => player.unMute();
+
+// Getting player info
+const getPlayerInfo = async () => {
+  const currentTime = await player.getCurrentTime();
+  const duration = await player.getDuration();
+  const state = await player.getPlayerState();
+};
+```
+
+### 4. Complete Migration Example
+
+For a complete migration example with all features, please see our [example applications](/example/).
+
+## Migration Checklist
+
+### ✅ Required Changes
+
+- [ ] Replace `YoutubePlayer` imports with `YoutubeView` and `useYouTubePlayer`
+- [ ] Move `playerVars` from component props to hook parameters
+- [ ] Replace event handler props with `useYouTubeEvent` hooks
+- [ ] Remove `useRef` and replace `playerRef.current.method()` with `player.method()`
+- [ ] Update component props (remove event handlers, keep styling props)
+- [ ] Replace manual state management with reactive event hooks
+
+### ✅ Optional Improvements
+
+- [ ] Simplify state management by using reactive values directly
+- [ ] Remove unnecessary `useState` calls for player-managed state
+- [ ] Add error handling with `useYouTubeEvent(player, 'error')`
+- [ ] Update TypeScript types if using TypeScript
+
+## Breaking Changes Summary
+
+- **Component**: `YoutubePlayer` → `YoutubeView` + `useYouTubePlayer`
+- **Event Props**: Removed, use `useYouTubeEvent` instead
+- **Player Control**: `playerRef.current.method()` → `player.method()`
+- **Configuration**: `playerVars` prop → hook parameters
+- **State Management**: Manual `useState` → reactive hook values
+
+The v2 API is designed to be more intuitive and reduce boilerplate code while providing the same functionality. Most applications will see a significant reduction in code complexity after migration.
+
+---
+
+## Previous Versions
+
+### [1.x.x] - Legacy Version
+See [v1 documentation](./v1.md) for the previous imperative API.
diff --git a/packages/react-native-youtube-bridge/docs/v1.md b/packages/react-native-youtube-bridge/docs/v1.md
new file mode 100644
index 0000000..89b224d
--- /dev/null
+++ b/packages/react-native-youtube-bridge/docs/v1.md
@@ -0,0 +1,315 @@
+# React Native Youtube Bridge (Version 1)
+
+## Overview
+Using a YouTube player in React Native requires complex setup and configuration.   
+However, there are currently no actively maintained YouTube player libraries for React Native. (The most popular react-native-youtube-iframe's [latest release was July 2, 2023](https://github.com/LonelyCpp/react-native-youtube-iframe/releases/tag/v2.3.0))   
+
+`react-native-youtube-bridge` is a library that makes it easy to use the [YouTube iframe Player API](https://developers.google.com/youtube/iframe_api_reference) in React Native applications.   
+
+- ✅ TypeScript support
+- ✅ iOS, Android, and Web platform support
+- ✅ New Architecture support
+- ✅ Works without YouTube native player modules
+- ✅ [YouTube iframe Player API](https://developers.google.com/youtube/iframe_api_reference) feature support
+- ✅ Developer-friendly API
+- ✅ Expo support
+- ✅ Flexible rendering modes (Inline HTML & WebView)
+
+## Example
+> For a quick start, check out the [example](/example/).
+
+- [Web Demo](https://react-native-youtube-bridge-example.pages.dev/)
+- [Expo Go](https://snack.expo.dev/@harang/react-native-youtube-bridge)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/react-native-bridges/react-native-youtube-bridge/main/assets/example.gif" width="600" />
+</p>
+
+## Installation
+
+```bash
+npm install react-native-youtube-bridge
+
+pnpm add react-native-youtube-bridge
+
+yarn add react-native-youtube-bridge
+
+bun add react-native-youtube-bridge
+```
+
+## Usage
+
+```tsx
+import { YoutubePlayer } from 'react-native-youtube-bridge';
+
+function App() {
+  return (
+    <YoutubePlayer 
+      source={source} // youtube videoId or url
+      // OR source={{ videoId: 'AbZH7XWDW_k' }}
+      // OR source={{ url: 'https://youtube.com/watch?v=AbZH7XWDW_k' }}
+    />
+  )
+}
+```
+
+### Events
+The library fires [events](https://developers.google.com/youtube/iframe_api_reference#Events) to notify your application of YouTube iframe API state changes. You can subscribe to these events using callback functions.   
+
+> 🔔 Note - Wrap callback functions with `useCallback` for performance optimization and to prevent abnormal behavior.
+
+```tsx
+function App() {
+  const playerRef = useRef<PlayerControls>(null);
+
+  const handleReady = useCallback(() => {
+    console.log('Player is ready!');
+  }, []);
+
+  const handleStateChange = useCallback((state: PlayerState) => {
+    console.log('Player state changed:', state);
+  }, []);
+
+  const handlePlaybackRateChange = useCallback((rate: number) => {
+    console.log('Playback rate changed:', rate);
+  }, []);
+
+  const handlePlaybackQualityChange = useCallback((quality: string) => {
+    console.log('Playback quality changed:', quality);
+  }, []);
+
+  const handleAutoplayBlocked = useCallback(() => {
+    console.log('Autoplay was blocked');
+  }, []);
+
+  const handleError = useCallback((error: YouTubeError) => {
+    console.error('Player error:', error);
+  }, []);
+
+  return (
+    <YoutubePlayer
+      onReady={handleReady}
+      onStateChange={handleStateChange}
+      onError={handleError}
+      onPlaybackRateChange={handlePlaybackRateChange}
+      onPlaybackQualityChange={handlePlaybackQualityChange}
+      onAutoplayBlocked={handleAutoplayBlocked}
+    />
+  )
+}
+```
+
+### Functions
+You can control various player features like mute, play, volume, and more by calling YouTube iframe API [functions](https://developers.google.com/youtube/iframe_api_reference#Functions) through the `ref`.   
+
+```tsx
+function App() {
+  const playerRef = useRef<PlayerControls>(null);
+
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [currentTime, setCurrentTime] = useState(0);
+
+  const onPlay = useCallback(() => {
+    if (isPlaying) {
+      playerRef.current?.pause();
+      return;
+    }
+
+    playerRef.current?.play();
+  }, [isPlaying]);
+
+  const seekTo = useCallback((time: number, allowSeekAhead: boolean) => {
+    playerRef.current?.seekTo(time, allowSeekAhead);
+  }, []);
+
+  const stop = () => playerRef.current?.stop();
+
+  return (
+    <View>
+      <YoutubePlayer
+        ref={playerRef}
+        source={source}
+      />
+
+      <View style={styles.controls}>
+        <TouchableOpacity
+          style={[styles.button, styles.seekButton]}
+          onPress={() => seekTo(currentTime > 10 ? currentTime - 10 : 0)}
+        >
+          <Text style={styles.buttonText}>⏪ -10s</Text>
+        </TouchableOpacity>
+
+        <TouchableOpacity style={[styles.button, styles.playButton]} onPress={onPlay}>
+          <Text style={styles.buttonText}>{isPlaying ? '⏸️ Pause' : '▶️ Play'}</Text>
+        </TouchableOpacity>
+
+        <TouchableOpacity style={[styles.button, styles.stopButton]} onPress={stop}>
+          <Text style={styles.buttonText}>⏹️ Stop</Text>
+        </TouchableOpacity>
+
+        <TouchableOpacity
+          style={[styles.button, styles.seekButton]}
+          onPress={() => seekTo(currentTime + 10, true)}
+        >
+          <Text style={styles.buttonText}>⏭️ +10s</Text>
+        </TouchableOpacity>
+      </View>
+    </View>
+  )
+}
+```
+
+### Player Parameters
+You can customize the playback environment by configuring YouTube embedded player [parameters](https://developers.google.com/youtube/player_parameters#Parameters).
+
+```tsx
+function App() {
+  return (
+    <YoutubePlayer
+      source={source}
+      playerVars={{
+        autoplay: true,
+        controls: true,
+        playsinline: true,
+        rel: false,
+        muted: true,
+      }}
+    />
+  )
+}
+```
+
+### Styles
+You can customize the YouTube player's styling to match your application's design.
+
+```tsx
+function App() {
+  return (
+    <YoutubePlayer
+      source={source}
+      height={400}
+      width={200}
+      style={{
+        borderRadius: 10,
+      }}
+      // Web platform support
+      iframeStyle={{
+        aspectRatio: 16 / 9,
+      }}
+      // iOS, Android platform support
+      webViewStyle={{
+        // ...
+      }}
+      // iOS, Android platform support
+      webViewProps={{
+        // ...
+      }}
+    />
+  )
+}
+```
+
+### Playback Progress Tracking
+- If `progressInterval` is provided, the `onProgress` callback will be invoked at the specified interval (in milliseconds).
+- If `progressInterval` is `undefined`, `0`, or `null`, progress tracking is disabled and `onProgress` will not be called.
+
+```tsx
+function App() {
+  const handleProgress = useCallback((progress: ProgressData) => {
+    setCurrentTime(progress.currentTime);
+    setDuration(progress.duration);
+    setLoadedFraction(progress.loadedFraction);
+  }, []);
+
+  return (
+    <YoutubePlayer
+      source={source}
+      progressInterval={1000}
+      onProgress={handleProgress}
+    />
+  )
+}
+```
+
+### Player Rendering & Source Configuration (ios, android)
+
+**Inline HTML vs WebView Mode**   
+Control YouTube player rendering method and configure source URLs for compatibility.
+
+1. **Inline HTML Mode** (`useInlineHtml: true`) renders the player by loading HTML directly within the app. (default)
+2. **WebView Mode** (`useInlineHtml: false`) loads an external player page.
+   - The default URI is https://react-native-youtube-bridge.pages.dev.
+   - To use your own custom player page as an external WebView, build your player with `@react-native-youtube-bridge/web` and set the URL in the `webViewUrl` property. For detailed implementation instructions, please refer to the [Web Player Guide](https://github.com/react-native-bridges/react-native-youtube-bridge/tree/main/packages/web).
+
+> [!NOTE]
+> **webViewUrl Usage**
+> - When `useInlineHtml: true`: Set as the `baseUrl` for WebView source HTML.
+> - When `useInlineHtml: false`: Overrides the WebView source `uri`.
+>
+> **Embed Restriction Solution**: If you encounter `embed not allowed` errors with YouTube iframe when using inline HTML mode and videos don't load properly, switch to WebView mode to load YouTube iframe through an external player.
+
+```tsx
+// Inline HTML (default)
+<YoutubePlayer
+ source={source}
+ useInlineHtml
+/>
+
+// External WebView with custom player page
+<YoutubePlayer
+ source={source}
+ useInlineHtml={false}
+ // default: https://react-native-youtube-bridge.pages.dev
+ webViewUrl="https://your-custom-player.com"
+/>
+```
+
+**Custom Player Page**
+
+To use your own custom player page, you can build a React-based player using `@react-native-youtube-bridge/web`.
+
+```tsx
+import { YoutubePlayer } from '@react-native-youtube-bridge/web';
+
+function CustomPlayerPage() {
+  return <YoutubePlayer />;
+}
+
+export default CustomPlayerPage;
+```
+
+> For more details, please refer to the [Web Player Guide](https://github.com/react-native-bridges/react-native-youtube-bridge/tree/main/packages/web).
+
+### YouTube oEmbed API
+Use the `useYoutubeOEmbed` hook to fetch YouTube video metadata.  
+This hook only supports YouTube URLs.
+
+```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 <Text>Loading...</Text>;
+ if (error) return <Text>Error: {error.message}</Text>;
+ if (!oEmbed) return null;
+
+ return (
+   <>
+     <Text>{oEmbed.title}</Text>
+     <Image 
+       source={{ uri: oEmbed?.thumbnail_url }} 
+       style={{ width: oEmbed?.thumbnail_width, height: oEmbed?.thumbnail_height }} 
+     />
+   </>
+ )
+}
+```
+
+## Contributing
+
+See the [contributing guide](/CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
+
+## License
+
+[MIT](./LICENSE)