UPnPCast

https://github.com/yinnho/upnpcast
Admin
UPnPCast is a modern Android DLNA/UPnP casting library providing device discovery, media casting,...
Tokens:24,011
Snippets:210
Trust Score:4.9
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Local Development Setup and Commands

Source: https://github.com/yinnho/upnpcast/blob/master/CONTRIBUTING.md

Clone the repository, build the project, run tests, and install the demo app using Gradle commands.

```bash
git clone https://github.com/yinnho/UPnPCast.git
cd UPnPCast

./gradlew build

./gradlew test

./gradlew :app-demo:installDebug
```

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

### Quick Start UPnPCast Initialization and Casting

Source: https://github.com/yinnho/upnpcast/blob/master/RELEASE_NOTES.md

Initialize the DLNACast SDK and cast a media URL. This example demonstrates basic casting and volume control.

```kotlin
// Initialize
DLNACast.init(this)

// Smart cast to best available device
lifecycleScope.launch {
    val success = DLNACast.cast("http://your-video.mp4", "My Video")
    if (success) {
        // Control volume
        DLNACast.setVolume(50)
        
        // Get real-time progress
        val progress = DLNACast.getProgressRealtime()
        Log.d("Progress", "${'$'}progress.percentage * 100}%")
    }
}
```

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

### Media Control and State Monitoring Example

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Demonstrates controlling media playback (pausing), getting the current device state (connection, playback status, volume), retrieving playback progress, and seeking to a specific position. Requires a running `lifecycleScope` and handles potential exceptions.

```kotlin
lifecycleScope.launch {
    try {
        // Control playback
        DLNACast.control(DLNACast.MediaAction.PAUSE)
        
        // Monitor state
        val state = DLNACast.getState()
        Log.d("DLNA", "Device: ${state.currentDevice?.name}")
        Log.d("DLNA", "Playing: ${state.isPlaying}")
        Log.d("DLNA", "Volume: ${state.volume}")
        
        // Get progress
        val progress = DLNACast.getProgress()
        Log.d("DLNA", "Progress: ${progress.percentage * 100}%")
        
        // Seek to specific position (2 minutes)
        DLNACast.seek(120000)
        
    } catch (e: Exception) {
        Log.e("DLNA", "Control failed: ${e.message}")
    }
}
```

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

### Copy Local Configuration File

Source: https://github.com/yinnho/upnpcast/blob/master/SECURITY.md

Copy the example properties file to create a local configuration file for sensitive credentials.

```bash
cp gradle.properties.local.example gradle.properties.local
```

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

### Get Local File URL Example

Source: https://github.com/yinnho/upnpcast/blob/master/CHANGELOG.md

Shows how to obtain an HTTP URL for a local file using `getLocalFileUrl`, which can then be used with the `cast` function for manual control.

```kotlin
val fileUrl = DLNACast.getLocalFileUrl("/path/to/video.mp4")
if (fileUrl != null) {
    DLNACast.cast(fileUrl, "Local Video") { success ->
        // Handle result
    }
}
```

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

### Testing and Linting Commands

Source: https://github.com/yinnho/upnpcast/blob/master/CONTRIBUTING.md

Execute all tests, run lint checks, and install the demo app for testing purposes using Gradle.

```bash
# Run all tests
./gradlew test

# Run lint checks
./gradlew lint

# Test with the demo app
./gradlew :app-demo:installDebug
```

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

### DLNACast.init(context)

Source: https://context7.com/yinnho/upnpcast/llms.txt

Initializes the DLNA service and starts SSDP device discovery. This method must be called once before any other DLNACast operations.

```APIDOC
## DLNACast.init(context)

### Description
Initializes the DLNA service and sets up SSDP device discovery. Must be called once, typically in `Activity.onCreate()`, before any other `DLNACast` calls. Accepts an `Activity` or `Application` context (stores a weak reference to `applicationContext` internally).

### Method Signature
`DLNACast.init(context: Context)`

### Parameters
#### Path Parameters
- **context** (Context) - Required - The Android context to initialize the service with.
```

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

### Cast Local File Example

Source: https://github.com/yinnho/upnpcast/blob/master/CHANGELOG.md

Demonstrates how to cast a local file to a DLNA device using the `castLocalFile` function. Includes a callback for success or failure.

```kotlin
DLNACast.castLocalFile("/storage/emulated/0/video.mp4", "My Video") { success, message ->
    if (success) {
        println("Local casting successful!")
    } else {
        println("Failed: $message")
    }
}
```

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

### Get Progress

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Retrieves the current playback progress.

```APIDOC
## Get Progress

### Description
Retrieves the current playback progress. This is a synchronous function.

### Method
`fun DLNACast.getProgress(): Progress`

### Response
#### Success Response (200)
- **Progress** - An object containing the current playback progress information.
```

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

### Local Properties Configuration Example

Source: https://github.com/yinnho/upnpcast/blob/master/SECURITY.md

Configure Maven Central and GPG signing credentials in the local properties file. Ensure this file is not committed to version control.

```properties
# Maven Central credentials
ossrhUsername=your-sonatype-username
ossrhPassword=your-sonatype-password-or-token

# GPG signing configuration
signing.gnupg.executable=path-to-your-gpg-executable
signing.gnupg.keyName=your-gpg-key-id
signing.gnupg.passphrase=your-gpg-key-password
```

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

### Complete UPnPCast Integration Example

Source: https://context7.com/yinnho/upnpcast/llms.txt

An end-to-end Android Activity demonstrating the integration of UPnPCast for device discovery, casting media, monitoring playback progress, and controlling volume. Ensure DLNACast is initialized before use and cleaned up when the activity is destroyed.

```kotlin
class CastActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        DLNACast.init(this)

        lifecycleScope.launch {
            // 1. Discover devices
            val devices = DLNACast.search(timeout = 5000)
            val tv = devices.firstOrNull { it.isTV } ?: devices.firstOrNull()
            if (tv == null) { Log.e("DLNA", "No device found"); return@launch }

            // 2. Cast to the TV
            val url = "http://clips.vorwaerts-gmbh.de/big_buck_bunny.mp4"
            val started = DLNACast.castToDevice(tv, url, "Big Buck Bunny")
            if (!started) { Log.e("DLNA", "Cast failed"); return@launch }
            Log.d("DLNA", "Casting to ${tv.name}")

            // 3. Set initial volume
            DLNACast.setVolume(70)

            // 4. Poll progress every second for 10 seconds
            repeat(10) {
                delay(1000)
                val progress = DLNACast.getProgress()
                progress?.let { (cur, total) ->
                    val pct = if (total > 0) cur * 100 / total else 0
                    Log.d("DLNA", "Progress: $pct% (${cur / 1000}s / ${total / 1000}s)")
                }
            }

            // 5. Seek to 30 seconds
            DLNACast.clearProgressCache()
            DLNACast.seek(30_000L)

            val freshPos = DLNACast.getProgressRealtime()
            Log.d("DLNA", "Position after seek: ${freshPos?.first?.div(1000)}s")

            // 6. Pause, then stop
            DLNACast.pause()
            delay(3000)
            DLNACast.stop()

            val state = DLNACast.getState()
            Log.d("DLNA", "Final state: ${state.playbackState}") // STOPPED
        }
    }

    override fun onDestroy() {
        super.onDestroy() 
        DLNACast.cleanup()
    }
}
```

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

### Get Playback Progress

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Retrieves the current playback progress of the media. This is a synchronous operation.

```kotlin
fun DLNACast.getProgress(): Progress
```

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

### Initialize DLNACast Service

Source: https://context7.com/yinnho/upnpcast/llms.txt

Initialize the DLNA service and start SSDP device discovery by calling `DLNACast.init(context)` once, typically in `Activity.onCreate()`. Ensure `DLNACast.cleanup()` is called in `onDestroy()` to release resources.

```kotlin
import com.yinnho.upnpcast.DLNACast

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        DLNACast.init(this)
        // Library is now ready; proceed with search/cast operations
    }

    override fun onDestroy() {
        super.onDestroy()
        DLNACast.cleanup() // Always release resources
    }
}
```

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

### Advanced Volume Control with DLNACast

Source: https://github.com/yinnho/upnpcast/blob/master/RELEASE_NOTES.md

Demonstrates how to get current volume status, set a specific volume level, and toggle mute using the DLNACast API.

```kotlin
lifecycleScope.launch {
    // Get current volume
    val volume = DLNACast.getVolume()
    Log.d("Volume", "Level: ${'$'}volume.level, Muted: ${'$'}volume.isMuted")
    
    // Set volume to 75%
    DLNACast.setVolume(75)
    
    // Toggle mute
    DLNACast.setMute(!volume.isMuted)
}
```

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

### Local File Casting Example

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Scans for local video files, finds a video containing 'movie' in its name, searches for available DLNA devices, and casts the local file to the first found device. Requires a running `lifecycleScope` and handles potential exceptions.

```kotlin
lifecycleScope.launch {
    try {
        // Scan for local video files
        val localVideos = DLNACast.scanLocalVideos()
        
        // Find a video to cast
        val videoToPlay = localVideos.firstOrNull { it.name.contains("movie") }
        
        if (videoToPlay != null) {
            // Get available devices
            val devices = DLNACast.search()
            val device = devices.firstOrNull()
            
            if (device != null) {
                // Cast local file
                val success = DLNACast.castLocalFile(device, videoToPlay)
                Log.d("DLNA", "Local cast success: $success")
            }
        }
    } catch (e: Exception) {
        Log.e("DLNA", "Local cast failed: ${e.message}")
    }
}
```

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

### Get Volume

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Retrieves the current volume information.

```APIDOC
## Get Volume

### Description
Retrieves the current volume information. This is a synchronous function.

### Method
`fun DLNACast.getVolume(): Volume`

### Response
#### Success Response (200)
- **Volume** - An object containing the current volume information.
```

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

### Get Local File URL and Cast

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Obtain a URL for a local file and then cast it. This is useful for scenarios where the casting function requires a URL.

```kotlin
// Get local file URL for manual use
val fileUrl = DLNACast.getLocalFileUrl("/storage/emulated/0/video.mp4")
if (fileUrl != null) {
    DLNACast.cast(fileUrl, "My Local Video") { success ->
        // Handle result  
    }
}
```

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

### Get Playback Progress with DLNACast.getProgress()

Source: https://context7.com/yinnho/upnpcast/llms.txt

Returns the current playback position and total duration in milliseconds as a nullable Pair. It uses a 5-second cache with real-time interpolation for smooth progress display.

```kotlin
lifecycleScope.launch {
    val progress = DLNACast.getProgress()

    if (progress != null) {
        val (currentMs, totalMs) = progress
        val percentage = if (totalMs > 0) (currentMs * 100f / totalMs) else 0f
        Log.d("DLNA", "Progress: ${currentMs / 1000}s / ${totalMs / 1000}s (${percentage.toInt()} %)")
        // Example output: Progress: 47s / 596s (7%)
    } else {
        Log.w("DLNA", "No progress data — not connected or media not started")
    }

    // Polling example for a progress bar:
    // val handler = Handler(Looper.getMainLooper())
    // val poller = object : Runnable {
    //     override fun run() {
    //         lifecycleScope.launch {
    //             DLNACast.getProgress()?.let { (cur, total) ->
    //                 if (total > 0) progressBar.progress = (cur * 100 / total).toInt()
    //             }
    //         }
    //         handler.postDelayed(this, 1000)
    //     }
    // }
    // handler.post(poller)
}
```

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

### Get Volume Information

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Retrieves the current volume information for the casting session. This is a synchronous operation.

```kotlin
fun DLNACast.getVolume(): Volume
```

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

### Cast to Specific Device Example

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Searches for DLNA devices and casts a video to a specific device identified by its name. Requires a running `lifecycleScope` and handles potential exceptions during the casting process.

```kotlin
lifecycleScope.launch {
    try {
        // First, search for devices
        val devices = DLNACast.search(timeout = 5000)
        
        // Find your preferred device
        val targetDevice = devices.firstOrNull { it.name.contains("Living Room") }
        
        if (targetDevice != null) {
            // Cast to specific device
            val success = DLNACast.castToDevice(
                device = targetDevice,
                url = "http://your-video.mp4",
                title = "My Movie"
            )
            
            if (success) {
                Log.d("DLNA", "Successfully cast to ${targetDevice.name}")
            }
        }
    } catch (e: Exception) {
        Log.e("DLNA", "Cast failed: ${e.message}")
    }
}
```

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

### Cast Local File with Error Handling

Source: https://context7.com/yinnho/upnpcast/llms.txt

Stream a local file by starting an internal HTTP server. Use try/catch to handle potential `UPnPException` subclasses like `FileError`, `NetworkError`, or `DeviceError`.

```kotlin
lifecycleScope.launch {
    val devices = DLNACast.search(timeout = 5000)
    val targetDevice = devices.firstOrNull() ?: run {
        Log.e("DLNA", "No device found for local cast")
        return@launch
    }

    try {
        DLNACast.castLocalFile(
            filePath = "/storage/emulated/0/Movies/my_movie.mp4",
            device = targetDevice,
            title = "My Movie"
        )
        Log.d("DLNA", "Local file cast started successfully on ${targetDevice.name}")
    } catch (e: com.yinnho.upnpcast.internal.UPnPException.FileError) {
        Log.e("DLNA", "File not found or unreadable: ${e.message}")
    } catch (e: com.yinnho.upnpcast.internal.UPnPException.NetworkError) {
        Log.e("DLNA", "Network/connection error: ${e.message}")
    } catch (e: com.yinnho.upnpcast.internal.UPnPException.DeviceError) {
        Log.e("DLNA", "Device error: ${e.message}")
    } catch (e: Exception) {
        Log.e("DLNA", "Unexpected error: ${e.message}")
    }
}
```

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

### DLNACast.castLocalFile

Source: https://context7.com/yinnho/upnpcast/llms.txt

Casts a local file from device storage to a DLNA target by starting an internal NanoHTTPD HTTP server. Ports 8081–8090 are tried automatically. Throws typed UPnPException subclasses on failure. Does not return a Boolean; use try/catch for error handling.

```APIDOC
## DLNACast.castLocalFile(filePath, device, title)

### Description
Casts a local file from device storage to a DLNA target by starting an internal NanoHTTPD HTTP server. Ports 8081–8090 are tried automatically. Throws typed `UPnPException` subclasses on failure (`FileError`, `NetworkError`, `DeviceError`, `UnknownError`). Does not return a `Boolean` — use try/catch for error handling.

### Parameters
- **filePath** (String) - Required - The absolute path to the local file.
- **device** (Device) - Required - The target DLNA device.
- **title** (String) - Required - The title of the media file.

### Throws
- `com.yinnho.upnpcast.internal.UPnPException.FileError` - If the file is not found or unreadable.
- `com.yinnho.upnpcast.internal.UPnPException.NetworkError` - If a network or connection error occurs.
- `com.yinnho.upnpcast.internal.UPnPException.DeviceError` - If a device-specific error occurs.
- `Exception` - For any other unexpected errors.

### Example
```kotlin
lifecycleScope.launch {
    val devices = DLNACast.search(timeout = 5000)
    val targetDevice = devices.firstOrNull() ?: run {
        Log.e("DLNA", "No device found for local cast")
        return@launch
    }

    try {
        DLNACast.castLocalFile(
            filePath = "/storage/emulated/0/Movies/my_movie.mp4",
            device = targetDevice,
            title = "My Movie"
        )
        Log.d("DLNA", "Local file cast started successfully on ${targetDevice.name}")
    } catch (e: com.yinnho.upnpcast.internal.UPnPException.FileError) {
        Log.e("DLNA", "File not found or unreadable: ${e.message}")
    } catch (e: com.yinnho.upnpcast.internal.UPnPException.NetworkError) {
        Log.e("DLNA", "Network/connection error: ${e.message}")
    } catch (e: com.yinnho.upnpcast.internal.UPnPException.DeviceError) {
        Log.e("DLNA", "Device error: ${e.message}")
    } catch (e: Exception) {
        Log.e("DLNA", "Unexpected error: ${e.message}")
    }
}
```
```

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

### Get State

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Retrieves the current casting state of the library.

```APIDOC
## Get State

### Description
Retrieves the current casting state of the library. This is a synchronous function.

### Method
`fun DLNACast.getState(): State`

### Response
#### Success Response (200)
- **State** - An object containing the current casting state (e.g., `isConnected`, `isPlaying`).
```

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

### Basic DLNA Casting Operations in Kotlin

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Demonstrates initialization, device searching, smart casting, playback control, and cleanup. Ensure DLNACast.init is called in onCreate and DLNACast.cleanup in onDestroy. All operations should be performed within coroutines.

```kotlin
import com.yinnho.upnpcast.DLNACast

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // Initialize
        DLNACast.init(this)
        
        // Use coroutines for all operations
        lifecycleScope.launch {
            searchDevices()
            performSmartCast()
        }
    }
    
    private suspend fun searchDevices() {
        try {
            // Device discovery with timeout
            val devices = DLNACast.search(timeout = 5000)
            Log.d("DLNA", "Found ${devices.size} devices")
            
            // Display devices
            devices.forEach { device ->
                val icon = if (device.isTV) "📺" else "📱"
                Log.d("DLNA", "$icon ${device.name} (${device.address})")
            }
        } catch (e: Exception) {
            Log.e("DLNA", "Search failed: ${e.message}")
        }
    }
    
    private suspend fun performSmartCast() {
        try {
            // Smart cast - automatically finds and selects best device
            val success = DLNACast.cast("http://your-video.mp4", "Video Title")
            if (success) {
                Log.d("DLNA", "Smart casting started!")
                controlPlayback()
            } else {
                Log.e("DLNA", "Cast failed")
            }
        } catch (e: Exception) {
            Log.e("DLNA", "Cast error: ${e.message}")
        }
    }
    
    private suspend fun controlPlayback() {
        try {
            // Control playback
            val pauseSuccess = DLNACast.control(DLNACast.MediaAction.PAUSE)
            Log.d("DLNA", "Paused: $pauseSuccess")
            
            // Get current state
            val state = DLNACast.getState()
            Log.d("DLNA", "Connected: ${state.isConnected}, Playing: ${state.isPlaying}")
            
            // Seek to 30 seconds
            val seekSuccess = DLNACast.seek(30000)
            Log.d("DLNA", "Seeked to 30 seconds: $seekSuccess")
        } catch (e: Exception) {
            Log.e("DLNA", "Control error: ${e.message}")
        }
    }
    
    override fun onDestroy() {
        super.onDestroy()        DLNACast.cleanup()
    }
}
```

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

### Configure JitPack Repository for UPnPCast

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Add the JitPack repository to your root build.gradle file if you prefer to use JitPack for dependency management.

```gradle
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}
```

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

### Get Current Casting State

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Retrieves the current state of the casting session, including connection status and playback state. This is a synchronous operation.

```kotlin
fun DLNACast.getState(): State
```

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

### Use Smart Casting

Source: https://github.com/yinnho/upnpcast/blob/master/docs/FAQ.md

Employ `smartCast` to automatically select the best device, potentially skipping manual selection.

```kotlin
// 使用智能搜索
DLNACast.smartCast(url, title, { success ->
    // 自动选择最佳设备，跳过手动选择过程
}) { devices ->
    devices.firstOrNull { it.isTV } // 优先选择电视
}
```

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

### Monitor Playback Progress (New API)

Source: https://github.com/yinnho/upnpcast/blob/master/docs/FAQ.md

Use the `getProgress` callback for real-time playback progress updates, calculating percentage and updating UI.

```kotlin
// 方案1：使用新的播放进度API (推荐)
DLNACast.getProgress { currentMs, totalMs, success ->
    if (success) {
        val progressPercent = if (totalMs > 0) (currentMs * 100 / totalMs) else 0
        Log.d("DLNA", "播放进度: $progressPercent% (${currentMs}ms / ${totalMs}ms)")
        
        // 更新UI进度条
        updateProgressBar(currentMs, totalMs)
    }
}
```

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

### Initialization

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Initializes the DLNACast library. This should be called once, typically in the `onCreate` method of your Activity.

```APIDOC
## Initialize

### Description
Initializes the DLNACast library. This should be called once, typically in the `onCreate` method of your Activity.

### Method
`DLNACast.init(context: Context)`

### Parameters
#### Path Parameters
- **context** (Context) - Required - The application context.
```

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

### DLNA Seek and Progress API Usage

Source: https://github.com/yinnho/upnpcast/blob/master/CHANGELOG.md

Demonstrates how to use the DLNACast API to seek to a specific position in media playback and retrieve real-time progress information. Requires the DLNACast library to be initialized.

```kotlin
DLNACast.control(DLNACast.MediaAction.SEEK, 30 * 1000L) { success ->
    Log.d("DLNA", "Seek result: $success")
}
```

```kotlin
DLNACast.getProgress { currentMs, totalMs, success ->
    if (success) {
        val progress = (currentMs * 100 / totalMs).toInt()
        Log.d("DLNA", "Progress: $progress%")
    }
}
```

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

### Monitor Playback Progress (Periodic Polling)

Source: https://github.com/yinnho/upnpcast/blob/master/docs/FAQ.md

Implement periodic polling using `Handler` and `postDelayed` to fetch playback progress at regular intervals.

```kotlin
// 方案2：定期获取播放进度
private fun startProgressMonitoring() {
    val handler = Handler(Looper.getMainLooper())
    val runnable = object : Runnable {
        override fun run() {
            DLNACast.getProgress { currentMs, totalMs, success ->
                if (success) {
                    // 更新UI显示进度
                    updateProgress(currentMs, totalMs)
                }
            }
            handler.postDelayed(this, 1000) // 每秒查询一次
        }
    }
    handler.post(runnable)
}
```

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

### DLNACast.getProgress()

Source: https://context7.com/yinnho/upnpcast/llms.txt

Fetches the current playback progress, returning the current position and total duration in milliseconds as a nullable `Pair`. It employs a 5-second cache and includes real-time interpolation for playing media, adding elapsed time between refreshes to ensure smooth progress updates.

```APIDOC
## `DLNACast.getProgress()`

### Description
Returns the current playback position and total duration as `Pair<Long, Long>?` (both in milliseconds). Uses a 5-second cache with real-time interpolation: if playing, elapsed time is added to the cached position between refreshes for smooth progress display.

### Parameters
None

### Request Example
```kotlin
lifecycleScope.launch {
    val progress = DLNACast.getProgress()
    progress?.let {
        val (currentMs, totalMs) = it
        val percentage = if (totalMs > 0) (currentMs * 100f / totalMs) else 0f
        Log.d("DLNA", "Progress: ${currentMs / 1000}s / ${totalMs / 1000}s (${percentage.toInt()} %)")
    } ?: Log.w("DLNA", "No progress data — not connected or media not started")
}
```

### Response
#### Success Response (`Pair<Long, Long>?`)
- Returns a `Pair` where the first element is the current playback position in milliseconds (Long) and the second element is the total duration in milliseconds (Long). Returns `null` if progress data is unavailable.

#### Failure Response (null)
- Returns `null` if progress data cannot be retrieved (e.g., not connected or media not started).
```

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

### Get DLNA Cast State

Source: https://context7.com/yinnho/upnpcast/llms.txt

Retrieve the current state of the DLNA cast session. This method is synchronous and can be called from any thread. It provides information about connection status, current device, playback state, volume, and mute status.

```kotlin
val state = DLNACast.getState()

Log.d("DLNA", "Connected: ${state.isConnected}")
Log.d("DLNA", "Device: ${state.currentDevice?.name ?: "none"}")
Log.d("DLNA", "Playback: ${state.playbackState}")  // IDLE, PLAYING, PAUSED, BUFFERING, ERROR
Log.d("DLNA", "Playing: ${state.isPlaying}, Paused: ${state.isPaused}")
Log.d("DLNA", "Volume: ${if (state.volume >= 0) "${state.volume}%" else "unknown"}")
Log.d("DLNA", "Muted: ${state.isMuted}")
```

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

### Initialize DLNA Casting Library

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Call this method once in your Activity's onCreate to initialize the library. It requires the application context.

```kotlin
DLNACast.init(context: Context)
```

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

### Perform Smart Casting

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Automatically finds and selects the best available DLNA device to cast the provided URL and title. Returns true if casting was initiated successfully.

```kotlin
suspend fun DLNACast.cast(url: String, title: String? = null): Boolean
```

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

### DLNACast.refreshVolumeCache() / refreshProgressCache() / clearProgressCache()

Source: https://context7.com/yinnho/upnpcast/llms.txt

Methods for manual control and synchronization of volume and playback progress caches.

```APIDOC
## `DLNACast.refreshVolumeCache()` / `refreshProgressCache()` / `clearProgressCache()`

### Description
Manual cache control methods for advanced use cases. `refreshVolumeCache()` and `refreshProgressCache()` are suspend functions that force a fresh fetch from the device and return `true` on success. `clearProgressCache()` is synchronous and should be called when switching media to avoid stale interpolation.

### Methods
- `refreshVolumeCache()`: Suspend function.
- `refreshProgressCache()`: Suspend function.
- `clearProgressCache()`: Synchronous function.

### Parameters
None

### Response
- **refreshVolumeCache() / refreshProgressCache()**: `true` on success, `false` otherwise.
- **clearProgressCache()**: No return value.

### Request Example
```kotlin
lifecycleScope.launch {
    // Before switching to a new media URL, clear stale progress
    DLNACast.clearProgressCache()

    val newUrl = "http://example.com/new_video.mp4"
    DLNACast.castToDevice(selectedDevice, newUrl, "New Video")

    // Force-refresh volume after external change
    val volumeOk = DLNACast.refreshVolumeCache()
    Log.d("DLNA", "Volume cache refreshed: $volumeOk")

    // Force-refresh progress after resume
    val progressOk = DLNACast.refreshProgressCache()
    Log.d("DLNA", "Progress cache refreshed: $progressOk")
}
```

### Response Example
```json
// For refreshVolumeCache() and refreshProgressCache():
true
```
```

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

### Scan for Local Video Files

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Scans the device for available local video files. Returns a list of LocalVideo objects.

```kotlin
suspend fun DLNACast.scanLocalVideos(): List<LocalVideo>
```

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

### Handle No Devices Found Error

Source: https://github.com/yinnho/upnpcast/blob/master/docs/FAQ.md

Check if the `devices` list is empty after a search and display an appropriate error message to the user.

```kotlin
DLNACast.search(timeout = 10000) { devices ->
    if (devices.isEmpty()) {
        // 处理没有发现设备的情况
        showErrorMessage("未发现可用设备，请检查网络连接")
    } else {
        // 正常处理设备列表
    }
}
```

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

### Handle HTTPS Certificate Issues

Source: https://github.com/yinnho/upnpcast/blob/master/docs/FAQ.md

For self-signed certificates with HTTPS, consider setting up trust or using HTTP for testing.

```kotlin
// 对于自签名证书，可能需要设置信任
// 建议使用HTTP协议进行测试
```

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

### Add UPnPCast Dependency via JitPack

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Add this dependency to your app's build.gradle file after configuring the JitPack repository.

```gradle
dependencies {
    implementation 'com.github.yinnho:UPnPCast:1.1.2'
}
```

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

### Scan and Cast Local Videos

Source: https://context7.com/yinnho/upnpcast/llms.txt

Scan the device's media store for videos and cast the first found video to a discovered DLNA device. Handles potential errors during the casting process.

```kotlin
lifecycleScope.launch {
    val videos = DLNACast.scanLocalVideos(context = this@MainActivity)

    if (videos.isEmpty()) {
        Log.w("DLNA", "No local videos found")
        return@launch
    }

    videos.forEach { video ->
        Log.d("DLNA", "Video: ${video.title}, Duration: ${video.duration}, Size: ${video.size}")
        // Example output:
        // Video: vacation_clip.mp4, Duration: 00:02:35, Size: 142.3 MB
    }

    // Cast the first found video to a discovered device
    val devices = DLNACast.search()
    val device = devices.firstOrNull() ?: return@launch
    val firstVideo = videos.first()

    try {
        DLNACast.castLocalFile(firstVideo.path, device, firstVideo.title)
        Log.d("DLNA", "Casting '${firstVideo.title}' to ${device.name}")
    } catch (e: Exception) {
        Log.e("DLNA", "Local cast error: ${e.message}")
    }
}
```

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

### Synchronously Search Devices with CountDownLatch

Source: https://github.com/yinnho/upnpcast/blob/master/docs/FAQ.md

Utilize `CountDownLatch` for a blocking synchronous device search, with a specified timeout.

```kotlin
// 方案2：使用CountDownLatch
fun searchDevicesBlocking(): List<Device> {
    val latch = CountDownLatch(1)
    var result: List<Device> = emptyList()
    
    DLNACast.search { devices ->
        result = devices
        latch.countDown()
    }
    
    latch.await(10, TimeUnit.SECONDS)
    return result
}
```

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

### Implement Seekable SeekBar for Playback

Source: https://github.com/yinnho/upnpcast/blob/master/docs/FAQ.md

Integrate `SeekBar` with `setOnSeekBarChangeListener` to allow users to seek playback by dragging the thumb.

```kotlin
// 方案3：结合SeekBar实现可拖拽的进度条
private fun setupSeekBar() {
    seekBar.setOnSeekBarChangeListener(object : SeekBar.OnSeekBarChangeListener {
        override fun onProgressChanged(seekBar: SeekBar?, progress: Int, fromUser: Boolean) {
            if (fromUser && totalDuration > 0) {
                val targetPosition = (progress * totalDuration / 100).toLong()
                DLNACast.control(DLNACast.MediaAction.SEEK, targetPosition) { success ->
                    Log.d("DLNA", "跳转到 ${targetPosition}ms: $success")
                }
            }
        }
        
        override fun onStartTrackingTouch(seekBar: SeekBar?) {}
        override fun onStopTrackingTouch(seekBar: SeekBar?) {}
    })
}
```

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

### Cast Media to a Device

Source: https://context7.com/yinnho/upnpcast/llms.txt

Cast media content from a given URL to the best available DLNA device, prioritizing TVs. If no devices are cached, a 3-second search is performed automatically. Returns `true` on successful casting.

```kotlin
lifecycleScope.launch {
    val videoUrl = "http://clips.vorwaerts-gmbh.de/big_buck_bunny.mp4"

    val success = DLNACast.cast(url = videoUrl, title = "Big Buck Bunny")
    if (success) {
        Log.d("DLNA", "Smart cast started — playing on best available device")
    } else {
        Log.e("DLNA", "Cast failed: no devices available or connection error")
    }
}
```

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

### Adjust Device Discovery Timeout

Source: https://github.com/yinnho/upnpcast/blob/master/docs/FAQ.md

Reduce the search timeout for faster results, but be aware that slower devices might be missed.

```kotlin
// 调整搜索超时时间
DLNACast.search(timeout = 5000) { devices ->
    // 较短的超时时间可以更快获得结果
    // 但可能遗漏响应较慢的设备
}
```

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

### Define Device Information Data Type

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Defines the structure for device information, including ID, name, IP address, and whether it's a TV.

```kotlin
data class Device(
    val id: String,           // Unique device identifier
    val name: String,         // Display name (e.g., "Living Room TV")
    val address: String,      // IP address
    val isTV: Boolean         // Whether this is a TV device
)
```

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

### Manage Cast Service Lifecycle

Source: https://github.com/yinnho/upnpcast/blob/master/docs/BEST_PRACTICES.md

Implement `Service` to manage the lifecycle of the casting component. Initialize DLNA casting on `onCreate` and release resources on `onDestroy` to prevent leaks and ensure proper operation.

```kotlin
class CastService : Service() {
    private var isInitialized = false
    
    override fun onCreate() {
        super.onCreate()
        initializeCast()
    }
    
    private fun initializeCast() {
        if (!isInitialized) {
            DLNACast.init(this)
            isInitialized = true
        }
    }
    
    override fun onDestroy() {
        super.onDestroy()
        if (isInitialized) {
            DLNACast.release()
            isInitialized = false
        }
    }
}
```

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

### Cast Media Directly to a Device

Source: https://context7.com/yinnho/upnpcast/llms.txt

Use `castToDevice` to cast media to a specific device without device selection logic. This is suitable when the user has already chosen a device.

```kotlin
lifecycleScope.launch {
    val devices = DLNACast.search(timeout = 5000)
    val livingRoomTV = devices.firstOrNull { it.name.contains("Living Room") }

    if (livingRoomTV == null) {
        Log.w("DLNA", "Target device not found")
        return@launch
    }

    val success = DLNACast.castToDevice(
        device = livingRoomTV,
        url = "http://vjs.zencdn.net/v/oceans.mp4",
        title = "Ocean Video"
    )

    if (success) {
        Log.d("DLNA", "Casting to ${livingRoomTV.name} — success")
    } else {
        Log.e("DLNA", "Failed to cast to ${livingRoomTV.name}")
    }
}
```

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

### DLNACast.cast(url, title)

Source: https://context7.com/yinnho/upnpcast/llms.txt

Initiates media casting to the most suitable available device. If no devices are cached, it performs a brief search first.

```APIDOC
## DLNACast.cast(url, title)

### Description
Smart-casts media to the best available device (prefers TV devices). If no devices are currently cached it automatically performs a 3-second search first. Returns `true` on success. Accepts any HTTP/HTTPS URL pointing to MP4, MP3, JPEG, or PNG content.

### Method Signature
`suspend fun cast(url: String, title: String): Boolean`

### Parameters
#### Query Parameters
- **url** (String) - Required - The HTTP/HTTPS URL of the media content to cast.
- **title** (String) - Required - The title of the media content.

### Response
#### Success Response (Boolean)
- **true** - Indicates the cast operation was initiated successfully.
- **false** - Indicates the cast operation failed due to no available devices or a connection error.
```

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

### Seek Media Playback Position

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Seeks to a specific position in the media playback. The position should be provided in milliseconds.

```kotlin
suspend fun DLNACast.seek(positionMs: Long): Boolean
```

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

### Define Playback Progress Data Type

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Defines the structure for playback progress, including current position, total duration, and percentage.

```kotlin
data class Progress(
    val currentMs: Long,          // Current position in milliseconds
    val totalMs: Long,            // Total duration in milliseconds
    val percentage: Float         // Progress as percentage (0.0-1.0)
)
```

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

### Optimize Batch Casting Operations

Source: https://github.com/yinnho/upnpcast/blob/master/docs/BEST_PRACTICES.md

Use a queue to process casting requests sequentially, adding a delay between requests to avoid overwhelming the system. This improves performance and stability when casting multiple items.

```kotlin
class BatchCastManager {
    private val castQueue = mutableListOf<CastRequest>()
    private var isProcessing = false
    
    data class CastRequest(
        val device: Device,
        val url: String,
        val callback: (Boolean) -> Unit
    )
    
    fun addCastRequest(device: Device, url: String, callback: (Boolean) -> Unit) {
        castQueue.add(CastRequest(device, url, callback))
        processQueue()
    }
    
    private fun processQueue() {
        if (isProcessing || castQueue.isEmpty()) return
        
        isProcessing = true
        val request = castQueue.removeFirst()
        
        DLNACast.castToDevice(request.device, request.url) { success ->
            request.callback(success)
            
            // 处理下一个请求
            Handler().postDelayed({
                isProcessing = false
                processQueue()
            }, 1000) // 间隔1秒避免过于频繁
        }
    }
}
```

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

### Search for DLNA Devices

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Discovers available DLNA devices on the network. You can specify a timeout in milliseconds. Returns a list of Device objects.

```kotlin
suspend fun DLNACast.search(timeout: Long = 5000): List<Device>
```

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

### Cast Local Video Files

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Casts a local video file to a specified DLNA device. Requires a Device object and a LocalVideo object.

```kotlin
suspend fun DLNACast.castLocalFile(device: Device, video: LocalVideo): Boolean
```

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

### Initialize and Cleanup DLNA Cast

Source: https://context7.com/yinnho/upnpcast/llms.txt

Initialize the DLNA cast functionality by calling `init()` with the application context, typically in `onCreate()`. Ensure `cleanup()` is called in `onDestroy()` to release resources and prevent memory leaks. `cleanup()` stops discovery, disconnects, and cancels coroutines.

```kotlin
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        DLNACast.init(this)
    }

    override fun onDestroy() {
        super.onDestroy() 
        DLNACast.cleanup()
        // After this call, init() must be called again before any DLNACast operations
    }
}
```

```kotlin
// In a Service:
class CastService : Service() {
    override fun onCreate() {
        super.onCreate()
        DLNACast.init(this)
    }

    override fun onDestroy() {
        super.onDestroy()
        DLNACast.cleanup()
    }

    override fun onBind(intent: Intent?) = null
}
```

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

### DLNACast.scanLocalVideos

Source: https://context7.com/yinnho/upnpcast/llms.txt

Scans the device's media store for local video files and returns a List<DLNACast.LocalVideo>. Each LocalVideo contains details like id, title, path, duration, size, and durationMs.

```APIDOC
## DLNACast.scanLocalVideos(context)

### Description
Scans the device's media store for local video files and returns a `List<DLNACast.LocalVideo>`. Each `LocalVideo` has `id`, `title`, `path`, `duration` (formatted string), `size` (formatted string), and `durationMs` (raw milliseconds).

### Parameters
- **context** (Context) - Required - The Android context to use for scanning.

### Returns
- **List<DLNACast.LocalVideo>** - A list of local videos found on the device.

### LocalVideo Object Structure
- **id** (Long) - Unique identifier for the video.
- **title** (String) - The title of the video.
- **path** (String) - The file path of the video.
- **duration** (String) - The formatted duration of the video (e.g., "00:02:35").
- **size** (String) - The formatted size of the video (e.g., "142.3 MB").
- **durationMs** (Long) - The duration of the video in milliseconds.

### Example
```kotlin
lifecycleScope.launch {
    val videos = DLNACast.scanLocalVideos(context = this@MainActivity)

    if (videos.isEmpty()) {
        Log.w("DLNA", "No local videos found")
        return@launch
    }

    videos.forEach { video ->
        Log.d("DLNA", "Video: ${video.title}, Duration: ${video.duration}, Size: ${video.size}")
    }

    // Cast the first found video to a discovered device
    val devices = DLNACast.search()
    val device = devices.firstOrNull() ?: return@launch
    val firstVideo = videos.first()

    try {
        DLNACast.castLocalFile(firstVideo.path, device, firstVideo.title)
        Log.d("DLNA", "Casting '${firstVideo.title}' to ${device.name}")
    } catch (e: Exception) {
        Log.e("DLNA", "Local cast error: ${e.message}")
    }
}
```
```

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

### Synchronously Search Devices with Coroutines

Source: https://github.com/yinnho/upnpcast/blob/master/docs/FAQ.md

Use Kotlin coroutines and `suspendCoroutine` to perform asynchronous device searches in a blocking manner.

```kotlin
// 方案1：使用协程
suspend fun searchDevicesSync(): List<Device> {
    return suspendCoroutine { continuation ->
        DLNACast.search { devices ->
            continuation.resume(devices)
        }
    }
}
```

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

### Manage DLNA Cache

Source: https://context7.com/yinnho/upnpcast/llms.txt

Manually control the cache for volume and playback progress. Use `clearProgressCache()` before switching media to prevent stale data. `refreshVolumeCache()` and `refreshProgressCache()` are suspend functions to force an update from the device.

```kotlin
lifecycleScope.launch {
    // Before switching to a new media URL, clear stale progress
    DLNACast.clearProgressCache()

    val newUrl = "http://example.com/new_video.mp4"
    DLNACast.castToDevice(selectedDevice, newUrl, "New Video")

    // Force-refresh volume after external change
    val volumeOk = DLNACast.refreshVolumeCache()
    Log.d("DLNA", "Volume cache refreshed: $volumeOk")

    // Force-refresh progress after resume
    val progressOk = DLNACast.refreshProgressCache()
    Log.d("DLNA", "Progress cache refreshed: $progressOk")
}
```

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

### DLNACast.search(timeout)

Source: https://context7.com/yinnho/upnpcast/llms.txt

Discovers all DLNA/UPnP devices on the local network. Returns a list of discovered devices after the specified timeout.

```APIDOC
## DLNACast.search(timeout)

### Description
Discovers all DLNA/UPnP devices on the local network via SSDP. Returns a `List<DLNACast.Device>` after the specified `timeout` (default 5000 ms). Devices are sorted with TV devices first, then alphabetically by name. The `Device` data class exposes `id`, `name`, `address`, and `isTV`.

### Method Signature
`suspend fun search(timeout: Long = 5000): List<Device>`

### Parameters
#### Query Parameters
- **timeout** (Long) - Optional - The duration in milliseconds to search for devices. Defaults to 5000 ms.

### Response
#### Success Response (List<Device>)
- **id** (String) - The unique identifier of the device.
- **name** (String) - The human-readable name of the device.
- **address** (String) - The network address of the device.
- **isTV** (Boolean) - True if the device is identified as a TV, false otherwise.
```

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

### Create Feature Branch

Source: https://github.com/yinnho/upnpcast/blob/master/CONTRIBUTING.md

Create a new Git branch for developing a specific feature. Use a descriptive name for the branch.

```bash
git checkout -b feature/your-feature-name
```

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

### Smart Casting

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Automatically finds and selects the best available DLNA device to cast the media to.

```APIDOC
## Smart Cast

### Description
Automatically finds and selects the best available DLNA device to cast the media to. This is a suspend function.

### Method
`suspend fun DLNACast.cast(url: String, title: String? = null): Boolean`

### Parameters
#### Request Body
- **url** (String) - Required - The URL of the media to cast.
- **title** (String?) - Optional - The title of the media.

### Response
#### Success Response (200)
- **Boolean** - `true` if casting was initiated successfully, `false` otherwise.
```

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

### Define Local Video Data Type

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Defines the structure for local video file information, including path, name, size, and duration.

```kotlin
data class LocalVideo(
    val path: String,         // Full file path
    val name: String,         // Display name
    val size: Long,           // File size in bytes
    val duration: Long        // Duration in milliseconds
)
```

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

### Define Media Control Actions Enum

Source: https://github.com/yinnho/upnpcast/blob/master/README.md

Enumerates the possible media control actions: PLAY, PAUSE, STOP.

```kotlin
enum class MediaAction {
    PLAY, PAUSE, STOP
}
```
Tokens:
Raw