This page provides a detailed description of the functionality, usage, and precautions for WebUI invoking a local video player, offering users a complete operation guide.
WebUI supports launching a locally installed video player on the user's device (such as VLC or PotPlayer) via custom protocols (e.g., vlc:* and potplayer:*) to directly play the HTTP links of specified video files in download tasks. This feature bypasses browser playback format limitations and fully utilises the advanced functions of the local player.
Strong format compatibility: Supports playback of special video formats not natively supported by the browser (e.g., MKV, FLV in high definition).
Richer features: Can invoke advanced decoding, multiple audio track switching, subtitle adjustment, speed control and other exclusive functions of the local player.
Performance enhancement: The local player can utilise hardware acceleration to improve playback smoothness of high-bitrate videos.
All of the following conditions must be met, otherwise the local player cannot be launched properly.
A supported video player must be installed on the local device (official recommendation: VLC Media Player, PotPlayer).
The player must complete custom protocol registration (e.g., the vlc:// protocol must be associated with VLC Player). The registration method is provided in the next section.
The browser has not blocked custom protocol calls (on first use, the browser may prompt a message, requiring selection of "Allow" or "Always Allow").
After installing the VLC player normally, the following batch file must be used to register the custom protocol:
@echo off
setlocal EnableExtensions DisableDelayedExpansion
:: This installer writes a fixed protocol handler under Program Files so the
:: browser-supplied URL is never inserted into PowerShell source code.
fltmc >nul 2>&1 || (
echo ERROR: This script requires Administrator privileges.
echo Please right-click it and select "Run as administrator".
pause
exit /b 1
)
:: Locate VLC in either registry view before changing the protocol handler.
set "player_exe="
for /f "tokens=2,*" %%A in ('reg.exe query "HKLM\SOFTWARE\VideoLAN\VLC" /ve 2^>nul ^| findstr.exe /R /C:"REG_SZ"') do set "player_exe=%%B"
if not defined player_exe for /f "tokens=2,*" %%A in ('reg.exe query "HKLM\SOFTWARE\WOW6432Node\VideoLAN\VLC" /ve 2^>nul ^| findstr.exe /R /C:"REG_SZ"') do set "player_exe=%%B"
if not defined player_exe (
echo ERROR: VLC installation information was not found.
pause
exit /b 1
)
if not exist "%player_exe%" (
echo ERROR: VLC executable was not found: %player_exe%
pause
exit /b 1
)
echo Found VLC executable: %player_exe%
:: Install the embedded handler in an administrator-protected directory.
set "install_dir=%ProgramFiles%\BitComet\tools"
set "handler_path=%install_dir%\vlc_protocol_handler.ps1"
if not exist "%install_dir%" mkdir "%install_dir%" >nul 2>&1
if not exist "%install_dir%" (
echo ERROR: Failed to create handler directory: %install_dir%
pause
exit /b 1
)
set "VLC_INSTALLER_SOURCE=%~f0"
set "VLC_HANDLER_PATH=%handler_path%"
powershell.exe -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -Command "$ErrorActionPreference = 'Stop'; $lines = [IO.File]::ReadAllLines($env:VLC_INSTALLER_SOURCE); $begin = [Array]::IndexOf($lines, '# POWERSHELL_HANDLER_BEGIN'); $end = [Array]::IndexOf($lines, '# POWERSHELL_HANDLER_END'); if ($begin -lt 0 -or $end -le ($begin + 1)) { throw 'Embedded handler markers are invalid.' }; $payload = $lines[($begin + 1)..($end - 1)]; $temp = $env:VLC_HANDLER_PATH + '.tmp'; [IO.File]::WriteAllLines($temp, $payload, (New-Object Text.UTF8Encoding($false))); Move-Item -LiteralPath $temp -Destination $env:VLC_HANDLER_PATH -Force"
if errorlevel 1 (
echo ERROR: Failed to install the VLC protocol handler.
pause
exit /b 1
)
set "VLC_INSTALLER_SOURCE="
set "VLC_HANDLER_PATH="
:: Register the protocol machine-wide. The URL remains a quoted argument to a
:: fixed -File script and is never parsed as part of a -Command expression.
set "powershell_exe=%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe"
set "protocol_command=\"%powershell_exe%\" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File \"%handler_path%\" \"%%1\""
reg.exe add "HKLM\SOFTWARE\Classes\vlc" /ve /t REG_SZ /d "URL:VLC Protocol" /f >nul || goto :registration_failed
reg.exe add "HKLM\SOFTWARE\Classes\vlc" /v "URL Protocol" /t REG_SZ /d "" /f >nul || goto :registration_failed
reg.exe add "HKLM\SOFTWARE\Classes\vlc\shell\open\command" /ve /t REG_SZ /d "%protocol_command%" /f >nul || goto :registration_failed
echo VLC protocol registered successfully.
echo Handler installed at: %handler_path%
endlocal
pause
exit /b 0
:registration_failed
echo ERROR: Failed to write the VLC protocol registration.
endlocal
pause
exit /b 1
# POWERSHELL_HANDLER_BEGIN
param(
[Parameter(Mandatory = $true, Position = 0)]
[string] $ProtocolUrl
)
Set-StrictMode -Version 2.0
$ErrorActionPreference = 'Stop'
# Convert the custom protocol value into one validated HTTP(S) media URL.
function ConvertFrom-VlcProtocolUrl {
param(
[Parameter(Mandatory = $true)]
[string] $Value
)
$prefix = 'vlc://'
if ([string]::IsNullOrWhiteSpace($Value) -or
-not $Value.StartsWith($prefix, [StringComparison]::OrdinalIgnoreCase)) {
throw 'The VLC protocol URL must start with vlc://.'
}
$target = $Value.Substring($prefix.Length)
# Browsers serialize vlc://http://... as vlc://http//...; restore only
# the two explicitly supported inner schemes before URI validation.
if ($target.StartsWith('http//', [StringComparison]::OrdinalIgnoreCase)) {
$target = 'http://' + $target.Substring('http//'.Length)
}
elseif ($target.StartsWith('https//', [StringComparison]::OrdinalIgnoreCase)) {
$target = 'https://' + $target.Substring('https//'.Length)
}
$uri = $null
if (-not [Uri]::TryCreate($target, [UriKind]::Absolute, [ref] $uri)) {
throw 'The VLC protocol target is not an absolute URL.'
}
if (($uri.Scheme -ne 'http' -and $uri.Scheme -ne 'https') -or
[string]::IsNullOrWhiteSpace($uri.Host) -or
-not [string]::IsNullOrEmpty($uri.UserInfo)) {
throw 'Only HTTP(S) URLs without embedded credentials are allowed.'
}
return $uri.AbsoluteUri
}
# Read VLC's executable path from protected HKLM registry views.
function Get-VlcExecutablePath {
$views = @(
[Microsoft.Win32.RegistryView]::Registry64,
[Microsoft.Win32.RegistryView]::Registry32
)
foreach ($view in $views) {
$baseKey = $null
$vlcKey = $null
try {
$baseKey = [Microsoft.Win32.RegistryKey]::OpenBaseKey(
[Microsoft.Win32.RegistryHive]::LocalMachine,
$view
)
$vlcKey = $baseKey.OpenSubKey('SOFTWARE\VideoLAN\VLC')
if ($null -eq $vlcKey) {
continue
}
$candidate = [string] $vlcKey.GetValue('')
if (-not [string]::IsNullOrWhiteSpace($candidate) -and
(Test-Path -LiteralPath $candidate -PathType Leaf)) {
return $candidate
}
}
finally {
if ($null -ne $vlcKey) {
$vlcKey.Dispose()
}
if ($null -ne $baseKey) {
$baseKey.Dispose()
}
}
}
throw 'VLC executable was not found.'
}
# HANDLER_MAIN_BEGIN
try {
$targetUrl = ConvertFrom-VlcProtocolUrl -Value $ProtocolUrl
$playerExe = Get-VlcExecutablePath
# The executable and URL are separate arguments; no dynamic code is used.
& $playerExe $targetUrl
}
catch {
Write-Error $_.Exception.Message
exit 1
}
# POWERSHELL_HANDLER_ENDSave the code above as vlc_reg_v2.bat, then right-click it and select "Run as administrator". The single BAT file installs its embedded PowerShell handler at %ProgramFiles%\BitComet\tools\vlc_protocol_handler.ps1 and registers the VLC custom protocol.
After installing PotPlayer (64-bit version) normally, the PotPlayer custom protocol is configured by default. If the custom protocol fails, you can use the following batch file to repair it.
@echo off
setlocal enabledelayedexpansion
:: Check if the script is running with Administrator privileges
fltmc >nul 2>&1 || (
echo ERROR: This script requires Administrator privileges!
echo Please right-click and select "Run as administrator".
pause
exit /b 1
)
:: Find PotPlayer installation directory
for /f "tokens=1,2* delims=:" %%a in (
'reg query "HKLM\SOFTWARE\DAUM\PotPlayer64" /v "ProgramPath" 2^>nul ^| findstr "ProgramPath"'
) do (
for /f "tokens=1,2,3" %%l in ("%%a") do (
set "player_disk=%%n"
)
set "player_exe=!player_disk!:%%b"
)
:: Verify PotPlayerMini64.exe exists
if not exist "!player_exe!" (
echo PotPlayer executable not found: !player_exe!
pause
exit /b 1
) else (
echo Found PotPlayer executable path: !player_exe!
)
:: Start registering registry entries
:: Create potplayer root key with default value
reg add "HKCR\potplayer" /ve /t REG_SZ /d "URL:PotPlayer Protocol" /f >nul
:: Create URL Protocol entry (empty value)
reg add "HKCR\potplayer" /v "URL Protocol" /t REG_SZ /d "" /f >nul
:: Create shell\open\command entry with properly quoted executable path
reg add "HKCR\potplayer\shell\open\command" /ve /t REG_SZ /d "\"!player_exe!\" \"%%1\"" /f >nul
:: Verify registration result
if %errorlevel% equ 0 (
echo PotPlayer protocol registered successfully!
) else (
echo Failed to write to registry. Please run this script as Administrator.
pause
exit /b 1
)
endlocal
pauseAfter saving this .bat file locally, right-click and select 'Run as administrator' to register the PotPlayer custom protocol.