# react-native-tuiplayer

React Native 0.79+ bridge for the Tencent Cloud **TUIPlayer Kit** short video component. This package exposes the native Android and iOS short video player view as a declarative React component together with a lightweight initialization helper that configures the TUIPlayer core SDK (licence, logging, super-resolution resource).

The library is built with the React Native New Architecture in mind: it supports Fabric & TurboModules out of the box while still working when the new architecture is disabled.

## Features

- 🔄 Unified cross-platform API for configuring the TUI short video view
- 📱 Declarative `TUIShortVideoView` component with imperative control handle (pause/resume/start etc.)
- 🧩 Supports VOD, live and custom list items, including extra metadata (`extInfo`)
- ⚙️ Helper to initialise the native core (`initializePlayer`) and provide licence / logging configuration
- ✅ Compatible with RN 0.79.4 new architecture (Fabric + TurboModules) and classic bridge

## Installation

```bash
# Using npm
npm install react-native-tuiplayer

# or using yarn
yarn add react-native-tuiplayer
```

### Android setup

1. **Gradle configuration** – autolinking adds the library automatically. Ensure the root `settings.gradle` includes the React Native autolinking block (default for RN 0.79+).
2. **LiteAV Player dependency** – the library already declares `com.tencent.liteav:LiteAVSDK_Player:latest.release`, so no extra work is needed unless you want to pin a specific version.
3. **Licence** – initialise the SDK (see _Usage_ below) with the licence URL/key you obtained from Tencent Cloud.

> ℹ️  If you keep `android/gradle.properties` with `newArchEnabled=true`, the Fabric implementation is enabled automatically.

### iOS setup

1. In `ios/Podfile`, make sure you set the minimum platform to 12.0 or newer and keep the React Native generated post-install script.
2. Add the following to enable the new architecture if you plan to use it:

   ```ruby
   use_react_native!(
     :path => config[:reactNativePath],
     :fabric_enabled => true,
     :hermes_enabled => true
   )
   ENV['RCT_NEW_ARCH_ENABLED'] = '1'
   ```

3. Install pods:

   ```bash
   cd ios
   pod install
   ```

   The pod pulls in `TXLiteAVSDK_Player` plus both `TUIPlayerCore` and `TUIPlayerShortVideo` XCFrameworks that ship with the package.

4. Make sure you configure the Tencent Cloud licence (see _Usage_ below). Without a valid licence the player will fail to start.

## Usage

```tsx
import React, {useEffect, useRef} from 'react';
import {SafeAreaView} from 'react-native';
import {
  TUIShortVideoView,
  type TUIShortVideoViewHandle,
  initializePlayer,
  type VideoSource,
} from 'react-native-tuiplayer';

const SAMPLE_VIDEOS: VideoSource[] = [
  {
    id: 'video-1',
    type: 'vod',
    url: 'https://liteav.demo.vod/video1.mp4',
    coverUrl: 'https://liteav.demo.vod/video1.jpg',
  },
  {
    id: 'live-1',
    type: 'live',
    url: 'webrtc://liteavapp.qcloud.com/live/liteavdemoplayerstreamid',
    coverUrl: 'https://liteav.demo.vod/live-cover.jpg',
  },
];

export default function DemoScreen() {
  const playerRef = useRef<TUIShortVideoViewHandle>(null);

  useEffect(() => {
    initializePlayer({
      enableLog: true,
      licenseUrl: 'https://your-licence-url',
      licenseKey: 'YOUR-LICENCE-KEY',
    });
  }, []);

  return (
    <SafeAreaView style={{flex: 1}}>
      <TUIShortVideoView
        ref={playerRef}
        style={{flex: 1}}
        videos={SAMPLE_VIDEOS}
        playMode="listLoop"
        onVideoChanged={({index}) => {
          console.log('Current index', index);
        }}
        onReachEnd={() => {
          // Append more data if required.
        }}
      />
    </SafeAreaView>
  );
}
```

### Imperative control

The forwarded ref exposes:

```ts
playerRef.current?.pause();
playerRef.current?.resume();
playerRef.current?.setVideos(nextVideos);
playerRef.current?.appendVideos(moreVideos);
playerRef.current?.startPlayAt(5, true);
playerRef.current?.release();
```

### Event payloads

- `onVideoChanged({ index, video })`
- `onNetStatus({ video, status })`
- `onReachEnd({ index })`

`video` always matches the shape of the original `VideoSource` objects you supplied (with best-effort conversion from native models).

## Licence configuration

You **must** configure a valid Tencent Cloud media licence before playing any stream:

```ts
initializePlayer({
  licenseUrl: 'https://license-url-from-console',
  licenseKey: 'YOUR-LICENCE-KEY',
  enableLog: __DEV__,
});
```

For Android this wires through `TUIPlayerCore.init`, while on iOS it sets `TUIPlayerCore` plus `TXLiveBase` when the LiteAV SDK is present.

## Commands & Fabric support

- **Fabric / New Architecture**: the view manager uses `RCTLegacyViewManagerInteropComponentView` and Android `Fabric` bindings, so no additional setup is needed when `newArchEnabled=true`.
- **TurboModule**: `initializePlayer` and `setSuperResolutionResource` are provided through a TurboModule when the new architecture is enabled, and fall back to the classic bridge otherwise.

## Troubleshooting

- **Black screen / playback fails** – verify that the LiteAV SDK is present (Android dependency / iOS pod) and that you called `initializePlayer` with a valid licence.
- **`TXLiveBase is not available` warning on iOS** – the pod could not find `TXLiteAVSDK_Player`. Double-check that `pod install` completed successfully.
- **Large APK size** – the TUIPlayer AARs are bundled inside this package. If you already include them elsewhere, remove the duplicates to avoid conflicts.

## Contributing

Issues and pull requests are welcome. Please ensure you comply with the Tencent Cloud SDK licence when distributing applications built with this package.

## License

MIT
