# projection

**Repository Path**: ylwu/projection

## Basic Information

- **Project Name**: projection
- **Description**: 一个面向 VIDAA、HappyCast/乐播及其他 DLNA/UPnP MediaRenderer 的 Windows 桌面投屏工具。启动后自动搜索局域网设备，并把设备连接、媒体兼容性、字幕处理和播放记忆整合到同一条使用链路中。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 12
- **Forks**: 4
- **Created**: 2026-07-12
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: application-software

**Tags**: None

## README

# ProjectionTool

[简体中文](./README.md) | English

A Windows desktop casting tool for VIDAA, HappyCast/Lebocast, and other DLNA/UPnP MediaRenderer devices. It automatically discovers devices on the local network and brings device connection, media compatibility checks, subtitle handling, and playback resume into one streamlined workflow.

## Features

- Discover TVs automatically or connect manually with a TV IP address.
- Keep the player and playlist visible at the top, with reorder, pause, resume, stop, seek, volume, and automatic next-item playback.
- Add files, URLs, FTP/FTPS downloads, M3U8 playlists, and subtitle-related results to one playlist, or play them immediately.
- Run downloads, extraction, merging, and conversion jobs one at a time, then keep each result in the list or play it immediately.
- Save local-file playback positions and resume them later.

## Quick Start
1. Connect the computer and TV to the same local network, and open a DLNA receiver app on the TV.
2. Select a discovered TV at the top. If none appears, use **Manual Connection** and enter the TV IP.
3. Select files or enter an address on **Web URL Casting**. Items are added to the top playlist.
4. Double-click an item or choose **Play Now**. Use the top controls for playback, seeking, and volume.
5. For merging, downloading, subtitles, or compatibility conversion, follow progress and results in **Processing Queue**.

## Download for Windows

Release packages include Python, FFmpeg, so no additional runtime installation is required:

- Recommended: download `ProjectionTool-vX.X.X-Windows-x64.zip`, extract it, and run `ProjectionTool.exe`. This portable build starts faster and is best for regular use.
- Alternatively, download `ProjectionTool-vX.X.X-Windows-x64.exe`. This single-file build needs no extraction but unpacks runtime components on every launch.


## Run from Source

Double-click [启动投屏工具.bat](./启动投屏工具.bat), or drag a video file onto it. You can also run from PowerShell:

```powershell
git clone <repository-url>
cd projection
python -m pip install -r requirements.txt
python app.py
```

## Recommended Workflow

1. Select an automatically discovered TV in the top device list. If it is missing, select **Manual Connection**, enter its IP, and scan.
2. Open **File Casting** and select **Select Files and Add**. Multiple files enter the top playlist in selection order, while details for the first file are loaded. **Select M3U8 Directory and Add** adds playlists from a directory.
3. Arrange items with **Move Up / Move Down**. Select **Play Selected Now** or double-click an item. Natural completion advances to the next item; failed and skipped items do not block later playback.
4. For the loaded file, set the four-digit `MM:SS` start position. Expand **Advanced Settings (Audio, Subtitles, and Compatibility Processing)** for track selection, a compatibility copy, or a hard-subtitle job. **Add to Playlist** preserves ordering; **Play Now** promotes the item and replaces current playback.
5. Resolve a web video on **Web URL Casting**, select a quality, and choose **Add to Playlist** or **Play Now**. Use **Batch URLs / FTP** for multiple HTTP/HTTPS and FTP/FTPS addresses.
6. On **Processing Queue**, choose **Add to Playlist When Complete** or **Play When Complete**. Review status, progress, and ETA for strictly serial jobs, cancel a selected job, or play a completed result.
7. Use the always-visible top player to pause, resume, stop, seek by slider or time entry, and change volume. **Resume once after an unexpected interruption** can recover a dropped playback session.

The playlist belongs to the current application session and should not be treated as a queue persisted across restarts. Compatibility copies, hard-subtitled versions, and M3U8 merge results never modify their source files.

For local files, the TV continuously reads data from the computer. Cloud backups and upload-heavy tasks can compete for the same adapter and Wi-Fi airtime. One automatic recovery cannot replace available bandwidth; limit background uploads or use Ethernet/5 GHz Wi-Fi when the network is busy.

## Cast a Local M3U8 Playlist

Local M3U8 has two entry paths:

- **Add directly to the playlist:** select an individual `.m3u8` on **File Casting**, or use **Select M3U8 Directory and Add**. ProjectionTool recursively checks master and child playlists, media segments, initialization maps, and local keys. A ready playlist can load directly in playlist order without creating a new file.
- **Batch merge to MP4:** open **Processing Queue** and select **Batch Merge M3U8**. Add multiple directories in the dialog, remove entries, and reorder them with **Move Up / Move Down**. After confirmation, manifests are queued by directory order and then filename, with exactly one background job running at a time.

An individually loaded M3U8 can also create a merge job from **File Casting**. Its result first occupies its playlist position as a pending item, becomes ready in place, and follows the selected **Add to Playlist When Complete / Play When Complete** mode. H.264/AAC is normally remuxed; incompatible codecs are converted to H.264/AAC.

Referenced files must stay inside the master playlist directory or its subdirectories. Local manifests with network URLs or paths escaping that directory are rejected. Processing never modifies the original manifest or segments, so keep every segment until completion. Use **Web URL Casting** when a manifest references online segments.

## Cast a Web Video

1. Select a discovered or manually connected DLNA TV in the top area.
2. Open **Web URL Casting** and select **Paste and Analyze**, or enter an HTTP/HTTPS URL and select **Analyze Video**/press Enter.
3. Review the status and result table, then choose among **Recommended**, **Compatible**, **HLS**, and **TV Support Required** qualities. The recommended stream is selected automatically.
4. Select **Add to Playlist** to preserve current ordering, or **Play Now** to promote the result and replace current playback. If a temporary URL expires or extraction fails, use **Analyze Again**, edit the URL, or copy the error details.
5. For multiple addresses, select **Batch URLs / FTP** and enter one HTTP, HTTPS, FTP, or FTPS URL per line. HTTP/HTTPS entries are resolved strictly serially and appear as pending playlist items first.

## Play After an FTP/FTPS Download

Enter one FTP/FTPS URL on **Web URL Casting**, or add one URL per line through **Batch URLs / FTP**. 
FTP/FTPS shares the same strictly serial queue as other processing jobs. ProjectionTool downloads the complete file to `Videos\随享投屏输出`; the playlist item remains pending until the file is fully downloaded and safely finalized, so progressive playback is not provided. Usernames and passwords are not shown in the playlist, written to logs, or saved in configuration. Even so, do not share the original credential-bearing URL.

## Processing Queue and Output Files

**Processing Queue** handles M3U8 merges, FTP/FTPS downloads, batch web resolution, compatibility processing, and hard-subtitle jobs through one background worker, so execution is strictly serial. Jobs can be queued or cancelled. A corresponding pending playlist item is inserted when submitted; success updates that item in place to a local file or web video, while failure/cancellation remains visible without silently reordering the playlist.

Select one result mode before submitting jobs:

- **Add to Playlist When Complete:** the ready result stays in its original position and waits for normal playlist order.
- **Play When Complete:** the ready result is promoted automatically, the old playback item is stopped and skipped, and the result starts immediately.

## Subtitle Notes

DLNA does not require TVs to support embedded MKV subtitles, MP4 soft subtitles, or external SRT files consistently. ProjectionTool can mark a subtitle as default and declare an external subtitle alongside the media URL, but final rendering depends on the TV player.

**Create Compatibility Copy** performs fast, lossless remuxing but cannot help when a TV ignores soft subtitles entirely. **Create Hard-Subtitled Version** re-encodes the full image, so processing time depends on duration, resolution, and available GPU encoding support. Hard-subtitle jobs are monitored on **Processing Queue**; there is no separate subtitle-jobs page.

## How Port Detection Works

The normal path uses SSDP discovery, through which the TV returns its device-description URL and port. The top **Manual Connection** dialog is the fallback and checks:

- Common device ports: `80`, `3000`, `5000`, `7000`, `8000`, `8008`, `8060`, `8080`, and `8888`.
- The common VIDAA/HappyCast dynamic range, `49152-49200` by default and editable in the dialog.
- Common UPnP description files on open ports, then the actual control URL from the device description.

Do not set the range to `1-65535`. A full scan is unnecessary on a local network, takes much longer, and is more likely to be blocked by a firewall.

## Troubleshooting
- **TV not found?** Confirm both devices are on the same local network, disable guest-network isolation, and allow the app through Windows Firewall on private networks.
- **Playback interrupted?** Prefer Ethernet or 5 GHz Wi-Fi and reduce heavy transfers on the computer.
- **Subtitles missing?** TV support varies; try a hard-subtitled copy.
- **Web video unavailable?** The address may have expired, require a login, or use DRM. Protected content is not supported.
- **Logs:** `%LOCALAPPDATA%\ProjectionTool\logs\projection.log`.