### Usage Guide - Quick Start

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/_COMPLETION_REPORT.md

Instructions for quickly starting with the documentation by navigating to the entry point file.

```text
1. 打开 `00-START-HERE.md`
2. 阅读 "五分钟快速导航" 部分
3. 根据需求点击相应的文档链接
```

--------------------------------

### React Integration Example

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/api-reference/VideoPlayer.md

Provides a complete example of integrating the VideoPlayer into a React component. It covers initialization, event handling, and player control methods like start, stop, startRecord, and stopRecord.

```javascript
import { useRef, useEffect, useState } from 'react';
import VideoPlayer from 'nodeplayer-addon/video-player';

export default function Player({ url }) {
  const videoRef = useRef(null);
  const playerRef = useRef(null);
  const [status, setStatus] = useState('Ready');
  const [recording, setRecording] = useState(false);

  useEffect(() => {
    if (!videoRef.current) return;

    const player = new VideoPlayer(videoRef.current, 'react-player');
    
    player.on('event', (code, msg) => {
      const messages = {
        1000: 'Connecting', 1001: 'Connected',
        1002: 'Failed', 3001: 'Recording',
      };
      setStatus(messages[code] || `Event ${code}`);
      if (code === 3001) setRecording(true);
      if (code === 3002 || code === 3003) setRecording(false);
    });

    player.on('error', (err) => {
      setStatus(`Error: ${err.message}`);
    });

    playerRef.current = player;
    return () => player.stop();
  }, []);

  return (
    <div>
      <video ref={videoRef} autoPlay muted style={{ width: '100%' }} />
      <div>{status}</div>
      <button onClick={() => playerRef.current?.start(url)}>Start</button>
      <button onClick={() => playerRef.current?.stop()}>Stop</button>
      <button onClick={() => {
        if (playerRef.current?.isRecording) {
          playerRef.current.stopRecord();
        } else {
          playerRef.current?.startRecord();
        }
      }}>
        {recording ? 'Stop Recording' : 'Record'}
      </button>
    </div>
  );
}
```

--------------------------------

### Complete Player Configuration Examples

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/configuration.md

Provides example configurations for different player scenarios: live monitoring, standard VOD, HD VOD, and low-end devices. These examples demonstrate tuning maxBufferDuration, keepBehindDuration, targetAhead, and maxAhead for specific use cases.

```javascript
// 场景1：实时直播监控（低延迟）
const monitorPlayer = new VideoPlayer(videoEl, 'monitor', {
  maxBufferDuration: 20,
  keepBehindDuration: 1,
  targetAhead: 0.1,
  maxAhead: 0.5
});

// 场景2：标清点播（均衡）
const vodPlayer = new VideoPlayer(videoEl, 'vod', {
  maxBufferDuration: 30,   // 默认
  keepBehindDuration: 5,   // 默认
  targetAhead: 0.3,        // 默认
  maxAhead: 3              // 默认
});

// 场景3：高清点播（高质量）
const hdPlayer = new VideoPlayer(videoEl, 'hd', {
  maxBufferDuration: 60,
  keepBehindDuration: 10,
  targetAhead: 1.0,
  maxAhead: 5
});

// 场景4：低端设备（低内存）
const lowEndPlayer = new VideoPlayer(videoEl, 'lowend', {
  maxBufferDuration: 10,
  keepBehindDuration: 2,
  targetAhead: 0.3,
  maxAhead: 1
});
```

--------------------------------

### Vue 3 Integration Example

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/api-reference/VideoPlayer.md

Demonstrates how to integrate the VideoPlayer into a Vue 3 application using the Composition API. It includes setup for the video element, event listeners, and player controls.

```vue
<template>
  <div>
    <video ref="videoEl" autoplay muted style="width: 100%;" />
    <div>{{ status }}</div>
    <button @click="start">Start</button>
    <button @click="stop">Stop</button>
    <button @click="toggleRecord">
      {{ recording ? 'Stop Recording' : 'Record' }}
    </button>
  </div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import VideoPlayer from 'nodeplayer-addon/video-player';

const props = defineProps({ url: String });

const videoEl = ref(null);
const status = ref('Ready');
const recording = ref(false);
let player = null;

onMounted(() => {
  player = new VideoPlayer(videoEl.value, `vue-player-${Date.now()}`);
  
  player.on('event', (code, msg) => {
    const messages = {
      1000: 'Connecting', 1001: 'Connected',
      1002: 'Failed', 3001: 'Recording',
    };
    status.value = messages[code] || `Event ${code}`;
    if (code === 3001) recording.value = true;
    if (code === 3002 || code === 3003) recording.value = false;
  });

  player.on('error', (err) => {
    status.value = `Error: ${err.message}`;
  });
});

onUnmounted(() => player?.stop());

function start() { player?.start(props.url); }
function stop() { player?.stop(); }
function toggleRecord() {
  if (!player) return;
  player.isRecording ? player.stopRecord() : player.startRecord();
}
</script>
```

--------------------------------

### start(url: string)

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/api-reference/VideoPlayer.md

Starts streaming playback from the given URL. This method initiates the playback process by creating a player instance in the main process, subscribing to events, and initializing media source handling.

```APIDOC
## start(url: string)

### Description
Starts streaming playback from the provided URL. This asynchronous operation involves creating a player instance in the main process, subscribing to 'event', 'info', and 'data' events, initiating stream playback, and initializing the MediaSource to handle received data. If playback is already started or initialization fails, an 'error' event will be triggered.

### Parameters
#### Parameters
- **url** (string) - Required - The streaming URL. Supports RTSP, RTMP, and HTTP(S)-FLV protocols.

### Returns
Promise<void> - An asynchronous operation that starts the playback process.

### Example
```javascript
player.start('rtsp://example.com/live/stream')
  .catch(err => console.error('Failed to start:', err));
```
```

--------------------------------

### Start Recording

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/INDEX.md

Begins recording the video stream. No additional parameters are needed.

```javascript
player.startRecord()
```

--------------------------------

### Starting Video Playback

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/api-reference/VideoPlayer.md

Asynchronously starts streaming playback from a given URL. It handles player creation, event subscription, and media source initialization. Errors during startup will trigger the 'error' event.

```javascript
player.start('rtsp://example.com/live/stream')
  .catch(err => console.error('Failed to start:', err));
```

--------------------------------

### Starting Video Recording

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/api-reference/VideoPlayer.md

Asynchronously starts recording the current video stream to a specified file path. If no path is provided, a default path is used. This method returns a promise indicating success or failure, along with an error message or the output path.

```javascript
const result = await player.startRecord('/tmp/recording.mp4');
if (result.success) {
  console.log('Recording started:', result.path);
} else {
  console.error('Recording failed:', result.error);
}
```

--------------------------------

### Player Control: Start

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/endpoints.md

Starts playback for a specified player instance. This is a request-response type endpoint.

```APIDOC
## POST player:start

### Description
Starts playback for a specified player instance.

### Method
POST

### Endpoint
/player:start

### Parameters
#### Request Body
- **id** (string) - Required - The identifier of the player instance to start.

### Request Example
```json
{
  "id": "player1"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Documentation Features - Rich Examples

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/_COMPLETION_REPORT.md

Highlights the variety and quantity of code examples provided for different use cases.

```text
- 基础使用示例（创建、启动、停止）
- 高级功能示例（录制、截图、重连）
- 框架集成示例（React、Vue、原生JS）
- 错误处理示例（try-catch、事件处理）
```

--------------------------------

### Main Process Application Setup

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/configuration.md

Sets up the main Electron window and registers the NodePlayerAddon IPC handlers. It includes logic for determining the license path and handling window lifecycle events.

```javascript
// main.js
const { app, BrowserWindow, ipcMain } = require('electron');
const NodePlayerAddon = require('nodeplayer-addon');
const path = require('path');

let mainWindow;

function createWindow() {
  mainWindow = new BrowserWindow({
    width: 1024,
    height: 768,
    show: false,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      nodeIntegration: false,
      contextIsolation: true,
    },
  });

  // 配置IPC
  const licensePath = app.isPackaged
    ? path.join(process.resourcesPath, 'license.dat')
    : path.join(__dirname, 'assets', 'license.dat');

  try {
    NodePlayerAddon.registerIpc(ipcMain, {
      getWindow: () => {
        if (mainWindow && !mainWindow.isDestroyed()) {
          return mainWindow;
        }
        return null;
      },
      licensePath: licensePath,
    });
  } catch (err) {
    console.error('Failed to register IPC:', err);
    app.quit();
    return;
  }

  mainWindow.loadFile('index.html');

  // 调试用
  if (!app.isPackaged) {
    mainWindow.webContents.openDevTools();
  }

  mainWindow.on('ready-to-show', () => {
    mainWindow.show();
  });

  mainWindow.on('closed', () => {
    NodePlayerAddon.unregisterIpc(ipcMain);
    mainWindow = null;
  });
}

app.on('ready', createWindow);

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit();
  }
});

app.on('activate', () => {
  if (mainWindow === null) {
    createWindow();
  }
});
```

--------------------------------

### Player Control: Start Recording

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/endpoints.md

Starts recording for a specified player instance. This is a request-response type endpoint.

```APIDOC
## POST player:startRecord

### Description
Starts recording for a specified player instance.

### Method
POST

### Endpoint
/player:startRecord

### Parameters
#### Request Body
- **id** (string) - Required - The identifier of the player instance to start recording.

### Request Example
```json
{
  "id": "player1"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Start Streaming

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/INDEX.md

Initiates the streaming process for the player. Requires a URL.

```javascript
player.start(url)
```

--------------------------------

### Install NodePlayer Addon

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/docs/react-frontend.md

Install the NodePlayer Addon package into your Electron project using npm.

```bash
npm i nodeplayer-addon
```

--------------------------------

### player:start

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/types.md

Starts playback of a media stream for a given player ID and URL. Ensure the player is created before calling this method.

```APIDOC
## player:start

### Description
Starts playback of a media stream for a given player ID and URL. Ensure the player is created before calling this method.

### Method
POST

### Endpoint
/player/start

### Parameters
#### Request Body
- **playerId** (string) - Required - The ID of the player to start.
- **url** (string) - Required - The URL of the media stream to play.
```

--------------------------------

### IPC Response: Start Recording

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/types.md

Response after starting a recording. Includes success status, an error message if applicable, and the actual path of the saved recording file.

```javascript
{
  success: boolean,
  error?: string,
  path?: string
}
```

--------------------------------

### IPC Request: Start Recording

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/types.md

Initiate recording of the current media stream to a file. Optionally specify the output file path; otherwise, a default path will be used.

```javascript
{
  playerId: string,
  filePath?: string
}
```

--------------------------------

### Check if Playback Started

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/api-reference/VideoPlayer.md

Determine if the player has started playback.

```javascript
if (player.isStarted) {
  console.log('Playback started');
}
```

--------------------------------

### startRecord(filePath?: string): Promise<{success: boolean, error?: string, path?: string}>

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/api-reference/VideoPlayer.md

Begins recording the current playback stream to a specified file path. If no file path is provided, a default path with a timestamp will be used. This operation is asynchronous and may trigger an 'error' event if the player is not started.

```APIDOC
## startRecord(filePath?: string)

### Description
Starts recording the current playback stream. If `filePath` is not provided, a default path of `record_<playerId>_<timestamp>.mp4` will be used. This is an asynchronous operation. An 'error' event may be triggered if the player is not currently started.

### Parameters
#### Parameters
- **filePath** (string) - Optional - The output file path for the recording. Defaults to a generated path if not provided.

### Returns
Promise<{
  success: boolean,
  error?: string,
  path?: string
}> - An object indicating whether the recording started successfully, along with an error message or the output path if successful.

### Example
```javascript
const result = await player.startRecord('/tmp/recording.mp4');
if (result.success) {
  console.log('Recording started:', result.path);
} else {
  console.error('Recording failed:', result.error);
}
```
```

--------------------------------

### Start with Retry Logic

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/INDEX.md

Initiates streaming with built-in retry logic for handling disconnections.

```javascript
startWithRetry 示例
```

--------------------------------

### Handle Player Events

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/api-reference/VideoPlayer.md

Listen for player status changes and log them. This example maps common event codes to human-readable messages.

```javascript
player.on('event', (code, msg) => {
  const statusMap = {
    1000: 'Connecting...', 
    1001: 'Connected',
    1002: 'Connection failed',
    3001: 'Recording started',
    3002: 'Recording stopped'
  };
  console.log(statusMap[code] || `Event ${code}: ${msg}`);
});
```

--------------------------------

### Configure Main Process for NodePlayer Addon

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/docs/react-frontend.md

Edit the src/main/index.js file to import and register the NodePlayer Addon with Electron's IPC. This setup is crucial for enabling communication between the main and renderer processes for addon functionalities. Ensure the license path is correctly set for packaged applications.

```javascript
import { app, shell, BrowserWindow, ipcMain } from 'electron'
import { join } from 'path'
import { electronApp, optimizer, is } from '@electron-toolkit/utils'
import icon from '../../resources/icon.png?asset'
import NodePlayerAddon from 'nodeplayer-addon'

function createWindow() {
  // Create the browser window.
  const mainWindow = new BrowserWindow({
    width: 900,
    height: 670,
    show: false,
    autoHideMenuBar: true,
    ...(process.platform === 'linux' ? { icon } : {})
    webPreferences: {
      preload: join(__dirname, '../preload/index.js'),
      sandbox: false
    }
  })

  mainWindow.on('ready-to-show', () => {
    mainWindow.maximize();
    mainWindow.show()
  })

  mainWindow.webContents.setWindowOpenHandler((details) => {
    shell.openExternal(details.url)
    return { action: 'deny' }
  })

  // HMR for renderer base on electron-vite cli.
  // Load the remote URL for development or the local html file for production.
  if (is.dev && process.env['ELECTRON_RENDERER_URL']) {
    mainWindow.loadURL(process.env['ELECTRON_RENDERER_URL'])
  } else {
    mainWindow.loadFile(join(__dirname, '../renderer/index.html'))
  }

   mainWindow.on('closed', () => {
    NodePlayerAddon.unregisterIpc(ipcMain)
  })
  NodePlayerAddon.registerIpc(ipcMain, {
    getWindow: () => mainWindow,
    licensePath: app.isPackaged
      ? join(process.resourcesPath, 'license.dat')
      : join(__dirname, 'license.dat'),
  })
}

// This method will be called when Electron has finished
// initialization and is ready to create browser windows.
// Some APIs can only be used after this event occurs.
app.whenReady().then(() => {
  // Set app user model id for windows
  electronApp.setAppUserModelId('com.electron')

  // Default open or close DevTools by F12 in development
  // and ignore CommandOrControl + R in production.
  // see https://github.com/alex8088/electron-toolkit/tree/master/packages/utils
  app.on('browser-window-created', (_, window) => {
    optimizer.watchWindowShortcuts(window)
  })

  // IPC test
  ipcMain.on('ping', () => console.log('pong'))

  createWindow()

  app.on('activate', function () {
    // On macOS it's common to re-create a window in the app when the
    // dock icon is clicked and there are no other windows open.
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

// Quit when all windows are closed, except on macOS. There, it's common
// for applications and their menu bar to stay active until the user quits
// explicitly with Cmd + Q.
app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit()
  }
})

// In this file you can include the rest of your app's specific main process
// code. You can also put them in separate files and require them here.

```

--------------------------------

### IPC Request: Start Playback

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/types.md

Send this request to initiate playback of a media stream on a specific player. Requires the player ID and the stream URL.

```javascript
{
  playerId: string,
  url: string
}
```

--------------------------------

### Error Handling

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/_COMPLETION_REPORT.md

Comprehensive guide to error types, their triggers, and suggested solutions within the NodePlayerAddon.

```APIDOC
## Error Handling

### Error Types and Triggers

- **Native Module Loading Error**
  - Trigger: Failure to load essential native modules.
  - Solution: Ensure correct installation and environment setup.

- **Pipeline State Error**
  - Trigger: Incorrect state transitions within the media pipeline.
  - Solution: Review player state management and operation sequences.

- **IPC Error**
  - Trigger: Issues during Inter-Process Communication.
  - Solution: Verify IPC channel integrity and message formats.

- **Network and Connection Error**
  - Trigger: Problems establishing or maintaining network connections.
  - Solution: Check network connectivity and server status.

- **Recording Error**
  - Trigger: Failures during the video recording process.
  - Solution: Verify recording path permissions and disk space.

- **MediaSource Error**
  - Trigger: Issues related to MediaSource API usage.
  - Solution: Ensure correct MediaSource and SourceBuffer handling.

(Details for all 15+ error types, their specific triggers, and recommended solutions would be listed here.)
```

--------------------------------

### Get Audio Codec String

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/api-reference/VideoPlayer.md

Retrieve the string representing the audio codec, such as 'mp4a.40.2'.

```javascript
console.log(player.audioCodecString);  // "mp4a.40.2"
```

--------------------------------

### Validation Checklist - Code Validation

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/_COMPLETION_REPORT.md

Checklist for validating the code examples within the documentation.

```text
- [x] 所有代码示例都遵循项目风格
- [x] 没有测试代码被当作示例
- [x] 所有async/await用法正确
- [x] 所有错误处理都合理
```

--------------------------------

### Get Video Codec String

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/api-reference/VideoPlayer.md

Retrieve the string representing the video codec, such as 'avc1.64001f' for H.264.

```javascript
console.log(player.videoCodecString);  // "avc1.64001f"
```

--------------------------------

### Set NODE_ENV Environment Variable

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/configuration.md

Configure the application environment for development or production using the NODE_ENV variable. This is typically done when starting the npm script.

```bash
# 开发环境
NODE_ENV=development npm start

# 生产环境
NODE_ENV=production npm start
```

--------------------------------

### NodePlayerAddon Class

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/README.md

The NodePlayerAddon class provides core functionality for media playback and recording. It extends EventEmitter and offers methods for starting, stopping, and recording streams, as well as handling various player events.

```APIDOC
## NodePlayerAddon Class

**Location:** `dist/index.cjs`, `dist/index.mjs`

Inherits from `EventEmitter`.

### Constructor
```javascript
new NodePlayerAddon(options?: {licensePath?: string})
```

### Static Methods
- `registerIpc(ipcMain, options?)` - Registers the IPC handler.
- `unregisterIpc(ipcMain)` - Unregisters the IPC handler.

### Instance Methods
- `start(url: string): boolean` - Starts playback.
- `stop(): void` - Stops playback.
- `startRecord(filePath: string): void` - Starts recording.
- `stopRecord(): void` - Stops recording.

### Properties
- `isTrialMode: boolean` - Indicates if the addon is in trial mode.

### Events
- `'event'` - Player status event `(code: number, msg?: string)`
- `'info'` - Stream information event `(info: StreamInfo)`
- `'data'` - Media data event `(buffer: ArrayBuffer)`
- `'error'` - Error event `(error: Error)`
```

--------------------------------

### Initializing VideoPlayer Instance

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/api-reference/VideoPlayer.md

Shows how to create a new VideoPlayer instance, passing the video element, a unique player ID, and optional configuration options.

```javascript
const videoEl = document.getElementById('video');
const player = new VideoPlayer(videoEl, 'player-1', {
  maxBufferDuration: 30,
  keepBehindDuration: 5
});
```

--------------------------------

### Initialize Main Process with NodePlayerAddon

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/README.md

Sets up the Electron main process, initializes the NodePlayerAddon, and registers IPC handlers for player communication. Ensure the license path is correctly configured for packaged applications.

```javascript
// main.js
const { app, BrowserWindow, ipcMain } = require('electron');
const NodePlayerAddon = require('nodeplayer-addon');
const path = require('path');

let mainWindow;

const createWindow = () => {
  mainWindow = new BrowserWindow({
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
    },
  });

  mainWindow.loadFile('index.html');

  // 注册播放器IPC处理器
  NodePlayerAddon.registerIpc(ipcMain, {
    getWindow: () => mainWindow,
    licensePath: app.isPackaged
      ? path.join(process.resourcesPath, 'license.dat')
      : path.join(__dirname, 'license.dat'),
  });

  mainWindow.on('closed', () => {
    NodePlayerAddon.unregisterIpc(ipcMain);
  });
};

app.whenReady().then(createWindow);
```

--------------------------------

### Create Electron React Project

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/docs/react-frontend.md

Use the create-electron scaffold to initialize a new Electron React project. Follow the prompts to select React as the framework and configure additional options.

```bash
npm create @quick-start/electron
```

```bash
> npx
> "create-electron"

✔ Project name: … electron-app-react
✔ Select a framework: › react
✔ Add TypeScript? … No / Yes
✔ Add Electron updater plugin? … No / Yes
✔ Enable Electron download mirror proxy? … No / Yes

Scaffolding project in electron-app-react...

Done. Now run:

cd electron-app-react
npm install
npm run dev
```

--------------------------------

### UMD Video Player Initialization

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/README.md

Include the UMD bundle script and initialize the VideoPlayer.

```html
<script src="https://cdn.jsdelivr.net/npm/nodeplayer-addon/dist/video-player.umd.js"></script>
<script>
  const player = new VideoPlayer(videoEl, 'player-1');
</script>
```

--------------------------------

### Configuration Options

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/_COMPLETION_REPORT.md

Detailed documentation on all configuration options available for NodePlayerAddon and VideoPlayer.

```APIDOC
## Configuration Options

### NodePlayerAddon Constructor Options

- **option1** (type) - Default: value - Description of option1.
- **option2** (type) - Default: value - Description of option2.
(Details for all NodePlayerAddon options)

### Register Options

- **optionA** (type) - Default: value - Description of optionA.
- **optionB** (type) - Default: value - Description of optionB.
(Details for all Register options)

### VideoPlayer Constructor Options

- **optionX** (type) - Default: value - Description of optionX.
- **optionY** (type) - Default: value - Description of optionY.
(Details for all VideoPlayer options)

### Environment Variables

- **ENV_VAR_NAME** (type) - Description of the environment variable.

### Preload Configuration

- **preloadSetting** (type) - Description of preload settings.

### Main Process Configuration

- **mainProcessSetting** (type) - Description of main process configuration.

(Detailed descriptions, default values, and usage scenarios for all configuration options would be provided here.)
```

--------------------------------

### player:create

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/types.md

Creates a new player instance with the specified ID and optional configuration. This is the initial step before performing other player operations.

```APIDOC
## player:create

### Description
Creates a new player instance with the specified ID and optional configuration. This is the initial step before performing other player operations.

### Method
POST

### Endpoint
/player/create

### Parameters
#### Request Body
- **playerId** (string) - Required - The unique identifier for the player.
- **options** (object) - Optional - Configuration options for the player.
  - **licensePath** (string) - Optional - The path to the license file.
```

--------------------------------

### Get Player ID

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/api-reference/VideoPlayer.md

Retrieve the unique identifier for the player instance.

```javascript
console.log(player.id);  // 'player-1'
```

--------------------------------

### Access HTMLVideoElement

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/api-reference/VideoPlayer.md

Get the bound HTML video element to interact with its events.

```javascript
player.video.addEventListener('play', () => {
  console.log('Video playing');
});
```

--------------------------------

### Task Completion - Step 2: Documentation Structure

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/_COMPLETION_REPORT.md

Checklist items for structuring the documentation, including directory creation and file content.

```text
- [x] api-reference/ 目录创建
  - [x] NodePlayerAddon.md → 850行+的完整API
  - [x] VideoPlayer.md → 1200行+的完整API
- [x] types.md → 所有类型定义
- [x] endpoints.md → IPC通信完整参考
- [x] errors.md → 错误处理完整指南
- [x] configuration.md → 配置选项完整文档
- [x] README.md → 项目概览和基本流程
- [x] QUICKSTART.md → 快速开始指南
- [x] INDEX.md → 完整导航索引
- [x] 00-START-HERE.md → 入口文档
```

--------------------------------

### VideoPlayer Properties

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/README.md

Access properties of the VideoPlayer instance to get its state and information.

```javascript
- `id: string` - 播放器ID
- `video: HTMLVideoElement` - 绑定的video元素
- `isStarted: boolean` - 是否已启动
- `isReady: boolean` - 流是否就绪
- `isRecording: boolean` - 是否正在录制
- `videoCodecString: string | null` - 视频编码字符串
- `audioCodecString: string | null` - 音频编码字符串
```

--------------------------------

### Check if Player is Ready

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/api-reference/VideoPlayer.md

Verify if the media source is ready and available for actions like taking screenshots.

```javascript
if (player.isReady) {
  const screenshot = player.captureScreenshot();
}
```

--------------------------------

### VideoPlayer Instance Methods

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/README.md

Control playback, recording, and screenshots using VideoPlayer instance methods.

```javascript
- `start(url: string): Promise<void>` - 启动播放
- `stop(): Promise<void>` - 停止播放
- `startRecord(filePath?: string): Promise<IpcResponse>` - 开始录制
- `stopRecord(): Promise<IpcResponse>` - 停止录制
- `captureScreenshot(quality?: number): string | null` - 获取截图
- `saveScreenshot(filePath: string, quality?: number): Promise<IpcResponse>` - 保存截图
```

--------------------------------

### player:startRecord

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/types.md

Initiates recording of the current media stream for a specified player. An optional file path can be provided for the output.

```APIDOC
## player:startRecord

### Description
Initiates recording of the current media stream for a specified player. An optional file path can be provided for the output.

### Method
POST

### Endpoint
/player/startRecord

### Parameters
#### Request Body
- **playerId** (string) - Required - The ID of the player to start recording from.
- **filePath** (string) - Optional - The desired path for the output recording file.
```

--------------------------------

### Importing VideoPlayer

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/api-reference/VideoPlayer.md

Demonstrates how to import the VideoPlayer class using CommonJS, ES6 Modules, or an HTML script tag for UMD builds.

```javascript
// CommonJS
const VideoPlayer = require('nodeplayer-addon/video-player');
```

```javascript
// ES6 Module
import VideoPlayer from 'nodeplayer-addon/video-player';
```

```html
// HTML script标签（UMD）
<script src="https://cdn.jsdelivr.net/npm/nodeplayer-addon/dist/video-player.umd.js"></script>
```

--------------------------------

### Instance Properties

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/api-reference/VideoPlayer.md

Access and retrieve information about the VideoPlayer instance.

```APIDOC
## Instance Properties

### id: string

Read-only. The unique identifier of the player.

```javascript
console.log(player.id);  // 'player-1'
```

---

### video: HTMLVideoElement

Read-only. The bound HTML video element.

```javascript
player.video.addEventListener('play', () => {
  console.log('Video playing');
});
```

---

### isStarted: boolean

Read-only. Whether the player has started.

```javascript
if (player.isStarted) {
  console.log('Playback started');
}
```

---

### isReady: boolean

Read-only. Whether the media source is ready, which can be used to determine if a screenshot can be taken.

```javascript
if (player.isReady) {
  const screenshot = player.captureScreenshot();
}
```

---

### isRecording: boolean

Read-only. Whether recording is in progress.

```javascript
if (player.isRecording) {
  console.log('Currently recording');
}
```

---

### videoCodecString: string | null

Read-only. The video codec string, e.g., `"avc1.64001f"` (H.264) or `"hev1.1.6.L93.B0"` (H.265).

```javascript
console.log(player.videoCodecString);  // "avc1.64001f"
```

---

### audioCodecString: string | null

Read-only. The audio codec string.

```javascript
console.log(player.audioCodecString);  // "mp4a.40.2"
```
```

--------------------------------

### VideoPlayer Class

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/README.md

The VideoPlayer class is designed for front-end video playback. It allows for starting and stopping playback, recording, and capturing screenshots, interacting directly with an HTMLVideoElement.

```APIDOC
## VideoPlayer Class

**Location:** `dist/video-player.mjs`, `dist/video-player.umd.js`

### Constructor
```javascript
new VideoPlayer(
  videoElement: HTMLVideoElement,
  playerId: string,
  options?: VideoPlayerOptions
)
```

### Instance Methods
- `start(url: string): Promise<void>` - Starts playback.
- `stop(): Promise<void>` - Stops playback.
- `startRecord(filePath?: string): Promise<IpcResponse>` - Starts recording.
- `stopRecord(): Promise<IpcResponse>` - Stops recording.
- `captureScreenshot(quality?: number): string | null` - Captures a screenshot.
- `saveScreenshot(filePath: string, quality?: number): Promise<IpcResponse>` - Saves a screenshot.

### Properties
- `id: string` - The player ID.
- `video: HTMLVideoElement` - The bound video element.
- `isStarted: boolean` - Indicates if playback has started.
- `isReady: boolean` - Indicates if the stream is ready.
- `isRecording: boolean` - Indicates if recording is in progress.
- `videoCodecString: string | null` - The video codec string.
- `audioCodecString: string | null` - The audio codec string.

### Events
- `'event'` - Player status event `(code: number, msg?: string)`
- `'error'` - Error event `(error: Error)`
```

--------------------------------

### VideoPlayer Constructor

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/README.md

Initialize a VideoPlayer instance by providing the video element, player ID, and optional options.

```javascript
new VideoPlayer(
  videoElement: HTMLVideoElement,
  playerId: string,
  options?: VideoPlayerOptions
)
```

--------------------------------

### Task Completion - Step 1: Deep Analysis

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/_COMPLETION_REPORT.md

Checklist items for the deep analysis phase of documentation generation.

```text
- [x] 项目身份识别 → nodeplayer-addon v0.3.0
- [x] 入口点分析 → dist/index.cjs, dist/index.mjs, dist/video-player.mjs
- [x] 公开API表面识别 → 2个主类，18个方法
- [x] 架构理解 → Electron主-渲进程模型
- [x] 配置选项映射 → 6个选项组
- [x] IPC端点列表 → 10个处理器，3个事件通道
- [x] 模块关系图 → 完整的依赖和导出关系
- [x] 错误目录 → 15+个错误类型，全部触发条件
```

--------------------------------

### NodePlayerAddon Instance Methods

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/README.md

Control playback and recording using instance methods of NodePlayerAddon.

```javascript
- `start(url: string): boolean` - 启动播放
- `stop(): void` - 停止播放
- `startRecord(filePath: string): void` - 开始录制
- `stopRecord(): void` - 停止录制
```

--------------------------------

### Expose Player APIs via preload.js

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/configuration.md

Expose a comprehensive set of player-related APIs to the frontend using Electron's contextBridge and ipcRenderer. This includes player control, recording, screenshotting, and event listening.

```javascript
// preload.js
const { contextBridge, ipcRenderer } = require('electron');

// 定义所有播放器相关的API
const playerAPI = {
  // 播放器控制
  createPlayer: (id) => ipcRenderer.invoke('player:create', id),
  startPlayer: (id, url) => ipcRenderer.invoke('player:start', id, url),
  stopPlayer: (id) => ipcRenderer.invoke('player:stop', id),
  destroyPlayer: (id) => ipcRenderer.invoke('player:destroy', id),

  // 录制
  startRecord: (id, filePath) => ipcRenderer.invoke('player:startRecord', id, filePath),
  stopRecord: (id) => ipcRenderer.invoke('player:stopRecord', id),

  // 截图
  saveScreenshot: (id, filePath, base64Data) =>
    ipcRenderer.invoke('player:screenshot', id, filePath, base64Data),

  // 事件监听
  onEvent: (id, callback) => {
    const channel = `player:event:${id}`;
    const handler = (event, data) => callback(data);
    ipcRenderer.on(channel, handler);
    return () => ipcRenderer.removeListener(channel, handler);
  },

  onInfo: (id, callback) => {
    const channel = `player:info:${id}`;
    const handler = (event, info) => callback(info);
    ipcRenderer.on(channel, handler);
    return () => ipcRenderer.removeListener(channel, handler);
  },

  onData: (id, callback) => {
    const channel = `player:data:${id}`;
    const handler = (event, data) => callback(data);
    ipcRenderer.on(channel, handler);
    return () => ipcRenderer.removeListener(channel, handler);
  },
};

contextBridge.exposeInMainWorld('electronAPI', playerAPI);
```

--------------------------------

### Chaining on() and off() Methods

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/api-reference/VideoPlayer.md

Demonstrates how to chain multiple `on()` calls for event listeners. The `on()` and `off()` methods return the player instance, enabling method chaining.

```javascript
player
  .on('event', handleEvent)
  .on('error', handleError)
  .on('event', handleEvent2);
```

--------------------------------

### NodePlayerAddon Constructor

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/README.md

Instantiate the NodePlayerAddon class. Optionally provide a license path.

```javascript
new NodePlayerAddon(options?: {licensePath?: string})
```

--------------------------------

### VideoPlayer Constructor

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/api-reference/VideoPlayer.md

Initializes a new VideoPlayer instance. This class is responsible for managing media playback, recording, and screenshots in the Electron renderer process, communicating with the main process via IPC.

```APIDOC
## VideoPlayer Constructor

### Description
Initializes a new VideoPlayer instance. The `playerId` must be unique and is used for IPC communication with the main process. Options can be provided to customize buffering behavior and the IPC API object.

### Parameters
#### Parameters
- **videoElement** (HTMLVideoElement) - Required - The HTML video tag element.
- **playerId** (string) - Required - The unique identifier for the player.
- **options** (Object) - Optional - Player configuration options.
  - **options.api** (Object) - Optional - Custom IPC API object. Defaults to `window.electronAPI`.
  - **options.maxBufferDuration** (number) - Optional - Maximum buffer duration in seconds. Defaults to 30.
  - **options.keepBehindDuration** (number) - Optional - Buffer duration to keep behind the current playback position in seconds. Defaults to 5.
  - **options.targetAhead** (number) - Optional - Target ahead buffer duration in seconds. Defaults to 0.3.
  - **options.maxAhead** (number) - Optional - Maximum ahead buffer duration in seconds. Defaults to 3.

### Returns
VideoPlayer - A new VideoPlayer instance.

### Example
```javascript
const videoEl = document.getElementById('video');
const player = new VideoPlayer(videoEl, 'player-1', {
  maxBufferDuration: 30,
  keepBehindDuration: 5
});
```
```

--------------------------------

### ES Module Export

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/README.md

Import the main addon and the VideoPlayer module using ES Module syntax.

```javascript
// 主模块：index.mjs
import NodePlayerAddon from 'nodeplayer-addon';

// 视频播放器：video-player.mjs
import VideoPlayer from 'nodeplayer-addon/video-player';
```

--------------------------------

### Task Completion - Step 3: Content Rules

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/_COMPLETION_REPORT.md

Checklist items confirming adherence to content rules for documentation.

```text
- [x] 代码示例均为实际使用代码（非测试代码）
- [x] 参数表格式标准化（统一的Markdown表格）
- [x] 返回值文档完整（类型+说明）
- [x] 异常文档完整（错误类型+触发条件）
- [x] 跨引用完整（所有相关链接）
- [x] 源文件位置标注（dist/xxx.js）
- [x] 类型精确（无任何推测或猜测）
```

--------------------------------

### Player Buffering Options

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/configuration.md

Configure player buffering behavior using targetAhead and maxAhead options. Higher maxAhead allows more buffering, while lower values aggressively catch up to the live position.

```javascript
const livePlayer = new VideoPlayer(videoEl, 'player1', {
  targetAhead: 0.1,  // 目标延迟100ms
  maxAhead: 1.0      // 最多允许1秒延迟
});

const vodPlayer = new VideoPlayer(videoEl, 'player2', {
  targetAhead: 1.0,
  maxAhead: 5.0      // 允许更多缓冲
});
```

--------------------------------

### Documentation Features - Complete Navigation

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/_COMPLETION_REPORT.md

Highlights the extensive navigation features, including multiple index documents and learning paths.

```text
- 3个不同的导航文档（快速、详细、索引）
- 快速查询表（方法、事件、类型、错误）
- 学习路径建议（初级、中级、高级）
```

--------------------------------

### File Inventory Table

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/_COMPLETION_REPORT.md

A table listing all generated documentation files, their sizes, status, and purpose.

```markdown
| 文件 | 大小 | 状态 | 用途 |
|-----|------|------|------|
| 00-START-HERE.md | 7.4K | ✅ | 入口和快速导航 |
| README.md | 15K | ✅ | 项目概览和架构 |
| QUICKSTART.md | 12K | ✅ | 快速开始指南 |
| INDEX.md | 7.9K | ✅ | 完整导航索引 |
| types.md | 9.3K | ✅ | 类型定义和接口 |
| endpoints.md | 15K | ✅ | IPC端点完整参考 |
| errors.md | 14K | ✅ | 错误代码和处理 |
| configuration.md | 15K | ✅ | 配置选项和参数 |
| api-reference/NodePlayerAddon.md | 6.7K | ✅ | 主进程API文档 |
| api-reference/VideoPlayer.md | 13K | ✅ | 前端API文档 |
| MANIFEST.txt | 6.9K | ✅ | 文档清单和统计 |
```

--------------------------------

### NodePlayerAddon API Reference

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/_COMPLETION_REPORT.md

Documentation for the main NodePlayerAddon class, including its constructor, public methods, properties, and events.

```APIDOC
## Class: NodePlayerAddon

### Description
Provides the primary interface for interacting with the NodePlayerAddon functionality from the main process.

### Constructor

#### Parameters
- **options** (NodePlayerAddonOptions) - Required - Options for configuring the NodePlayerAddon instance.

### Public Methods

#### Method: create

##### Description
Creates a new instance of a video player.

##### Parameters
- **options** (RegisterOptions) - Required - Options for registering the video player.

##### Returns
- **string** - The ID of the created video player.

#### Method: start

##### Description
Starts playback for a specified video player.

##### Parameters
- **id** (string) - Required - The ID of the video player to start.

#### Method: stop

##### Description
Stops playback for a specified video player.

##### Parameters
- **id** (string) - Required - The ID of the video player to stop.

#### Method: destroy

##### Description
Destroys a specified video player instance.

##### Parameters
- **id** (string) - Required - The ID of the video player to destroy.

#### Method: startRecord

##### Description
Starts recording the output of a specified video player.

##### Parameters
- **id** (string) - Required - The ID of the video player to record.
- **options** (RecordOptions) - Optional - Options for the recording process.

#### Method: stopRecord

##### Description
Stops the recording for a specified video player.

##### Parameters
- **id** (string) - Required - The ID of the video player whose recording should stop.

#### Method: screenshot

##### Description
Takes a screenshot of the current frame for a specified video player.

##### Parameters
- **id** (string) - Required - The ID of the video player to take a screenshot from.
- **options** (ScreenshotOptions) - Optional - Options for the screenshot.

##### Returns
- **string** - The path to the saved screenshot file.

### Public Properties

- **propertyName1** (type) - Description
- **propertyName2** (type) - Description
(and so on for all 8 properties)

### Events

- **eventName1** (payloadType) - Description
- **eventName2** (payloadType) - Description
(and so on for all 5 events)
```

--------------------------------

### Main Process API - NodePlayerAddon

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/README.md

Manages the player in the Electron main process. Provides methods to register and unregister IPC handlers for communication with the renderer process. It also emits various events like 'event', 'info', 'data', and 'error'.

```APIDOC
## NodePlayerAddon

### Description
Manages the player in the Electron main process. Provides methods to register and unregister IPC handlers for communication with the renderer process. It also emits various events like 'event', 'info', 'data', and 'error'.

### Methods

- `registerIpc(ipcMain, options)`: Registers IPC handlers.
- `unregisterIpc(ipcMain)`: Unregisters IPC handlers.

### Events

- `event`: Emitted for general events.
- `info`: Emitted for informational messages.
- `data`: Emitted for data-related events.
- `error`: Emitted when an error occurs.
```

--------------------------------

### Frontend Video Player Integration

Source: https://github.com/nodemedia/nodeplayer-addon/blob/main/_autodocs/README.md

Integrates the VideoPlayer from the nodeplayer-addon into an HTML video element. This snippet demonstrates how to instantiate the player, listen for events, and control playback.

```html
<video id="video" autoplay muted playsinline></video>
```

```javascript
import VideoPlayer from 'nodeplayer-addon/video-player';

const videoEl = document.getElementById('video');
const player = new VideoPlayer(videoEl, 'player-1');

// 监听事件
player.on('event', (code, msg) => {
  console.log(`事件 ${code}: ${msg}`);
});

player.on('error', (err) => {
  console.error('错误:', err.message);
});

// 启动播放
player.start('rtsp://example.com/live');

// 停止播放
player.stop();
```