# DLNASDK

**Repository Path**: lucifinilsu/DLNASDK

## Basic Information

- **Project Name**: DLNASDK
- **Description**: 一份轻量、易用的 Android DLNA/UPnP 投屏库，帮助开发者快速为应用集成媒体投屏功能。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 0
- **Created**: 2025-07-02
- **Last Updated**: 2025-12-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DLNA 投屏 SDK

一份轻量、易用的 Android DLNA/UPnP 投屏库，帮助开发者快速为应用集成媒体投屏功能。

## ✨ 功能特性

- **设备发现**: 自动发现局域网内支持 DLNA/UPnP 的设备（如智能电视、电视盒子等）。
- **媒体投屏**: 支持将网络视频 URL 或本地视频文件投射到目标设备上播放。
- **HLS/M3U8 兼容**: 自动为 HLS (M3U8) 直播流生成兼容性元数据，提升在各类电视上的播放成功率。
- **播放控制**: 提供播放、暂停、停止等基本远程控制功能。
- **易于集成**: 设计简洁，只需几步即可集成到现有 Android 项目中。

---

## 🚀 快速接入

按照以下步骤，将 DLNA SDK 集成到您的 Android 项目中。

### 1. 添加依赖

**第 1 步：添加 JitPack 仓库**

在您的根目录 `settings.gradle.kts` 文件中，添加 JitPack 仓库地址：

```kotlin
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { setUrl("https://jitpack.io") } // 添加这一行
    }
}
```

**第 2 步：添加 SDK 依赖**

在您的主应用模块（通常是 `app`）的 `build.gradle.kts` 文件中，添加 `DLNASDK` 的依赖：

```kotlin
dependencies {
    // ...
    implementation("com.gitee.lucifinilsu:DLNASDK:0.0.5")
}
```

### 2. 添加权限

为了进行网络通信和发现设备，需要在 `AndroidManifest.xml` 文件中声明以下权限：

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

---

## 📖 使用方法

SDK 的核心是 `DLNAManager`，它是一个单例，负责所有投屏相关的操作。

### 1. 初始化 SDK

在使用任何功能之前，首先获取 `DLNAManager` 的实例。

```java
DLNAManager dlnaManager = DLNAManager.getInstance();
```

### 2. 搜索设备

注册一个设备发现监听器，然后开始搜索。

```java
// 创建监听器来接收设备发现的回调
DLNAManager.DeviceDiscoveryListener discoveryListener = new DLNAManager.DeviceDiscoveryListener() {
    @Override
    public void onDeviceDiscovered(Device device) {
        // 当发现新设备时回调
        // 可以在这里更新 UI，将设备添加到列表中
        Log.d("DLNA_SDK", "发现设备: " + device.getFriendlyName());
    }

    @Override
    public void onDeviceRemoved(Device device) {
        // 当设备离线时回调（当前版本暂未实现）
    }

    @Override
    public void onDiscoveryFinished() {
        // 当一轮搜索结束时回调（当前版本暂未实现）
    }
};

// 注册监听器
dlnaManager.registerDeviceDiscoveryListener(discoveryListener);

// 开始搜索设备
dlnaManager.startSearch();
```

**注意**: 在不需要搜索时，请调用 `stopSearch()` 并注销监听器以释放资源。

```java
// 停止搜索
dlnaManager.stopSearch();

// 注销监听器
dlnaManager.unregisterDeviceDiscoveryListener(discoveryListener);
```

### 3. 选择设备并投屏

从发现的设备列表中选择一个设备，然后调用 `cast` 方法进行投屏。

```java
// 假设从设备列表中获取了一个 Device 对象
Device selectedDevice = deviceList.get(0);

dlnaManager.setSelectedDevice(selectedDevice);

// 投屏网络视频
String videoUrl = "http://example.com/video.mp4";
dlnaManager.cast(videoUrl, ""); // 第二个参数 metaData 暂时留空

// 投屏本地视频文件
// String localVideoPath = "/sdcard/Movies/myvideo.mp4";
// dlnaManager.cast(localVideoPath, "");
```

### 4. 播放控制

可以对当前投屏的视频进行播放、暂停和停止操作。

```java
// 播放
dlnaManager.play();

// 暂停
dlnaManager.pause();

// 停止
dlnaManager.stop();
```

### 5. 操作回调

可以设置一个回调来监听投屏和控制操作的结果。

```java
dlnaManager.setCallback(new DLNAManager.DLNAManagerCallback() {
    @Override
    public void onActionSuccess(String action) {
        // 操作成功，action 的值为 "cast", "play", "pause", "stop"
        Log.d("DLNA_SDK", action + " 操作成功");
    }

    @Override
    public void onActionFailed(String action, String errorMessage) {
        // 操作失败
        Log.e("DLNA_SDK", action + " 操作失败: " + errorMessage);
    }
});
```

---

## 📚 API 参考

### `DLNAManager`

| 方法 | 描述 |
| :--- | :--- |
| `getInstance()` | 获取 `DLNAManager` 的单例对象。 |
| `startSearch()` | 开始在局域网内搜索 DLNA 设备。 |
| `stopSearch()` | 停止设备搜索。 |
| `getDiscoveredDevices()` | 获取已发现的设备列表 (`List<Device>`)。 |
| `registerDeviceDiscoveryListener(listener)` | 注册设备发现监听器。 |
| `unregisterDeviceDiscoveryListener(listener)` | 注销设备发现监听器。 |
| `setSelectedDevice(device)` | 设置当前要操作的目标设备。 |
| `getSelectedDevice()` | 获取当前已选择的设备。 |
| `setCallback(callback)` | 设置操作结果的回调。 |
| `cast(url, metaData)` | 将指定的媒体 URL 投射到已选择的设备。`url` 可以是网络或本地路径。SDK 会自动处理 HLS (M3U8) 链接的元数据。 |
| `play()` | 控制设备开始或恢复播放。 |
| `pause()` | 控制设备暂停播放。 |
| `stop()` | 控制设备停止播放。 |

### `Device`

设备的数据模型，代表一个物理设备。

| 方法 | 描述 |
| :--- | :--- |
| `getFriendlyName()` | 获取设备的友好名称，通常显示在 UI 上。 |
| `getUdn()` | 获取设备的唯一设备名 (UDN)，是设备的唯一标识符。 |
| `getIpAddress()` | 获取设备的 IP 地址。 |
| `getLocation()` | 获取设备描述文件 (XML) 的 URL。 |
| `getServices()` | 获取设备支持的所有服务的列表 (`List<Service>`)。 |
| `getService(serviceType)` | 根据服务类型（如 `urn:schemas-upnp-org:service:AVTransport:1`）获取特定的 `Service` 对象。 |
| `getPresentationUrl()` | 获取设备的展示页面 URL (如果有的话)。 |

### `Service`

服务的数据模型，代表设备提供的一项具体功能（如媒体播放）。

| 方法 | 描述 |
| :--- | :--- |
| `getServiceType()` | 获取服务的类型 URN。 |
| `getServiceId()` | 获取服务的 ID URN。 |
| `getControlURL()` | 获取该服务的控制端点 URL，用于发送 SOAP 指令。 |
| `getEventSubURL()` | 获取该服务的事件订阅 URL。 |

### `DeviceDiscoveryListener` (接口)

| 方法 | 描述 |
| :--- | :--- |
| `onDeviceDiscovered(device)` | 当发现一个新设备时被调用。 |
| `onDeviceRemoved(device)` | 当一个设备离线时被调用。 |
| `onDiscoveryFinished()` | 当一轮搜索结束时被调用。 |

### `DLNAManagerCallback` (接口)

| 方法 | 描述 |
| :--- | :--- |
| `onActionSuccess(action)` | 当一个操作（如 `cast`, `play`）成功时被调用。 |
| `onActionFailed(action, errorMessage)` | 当一个操作失败时被调用。 |