Add runtime encoder compatibility validation

2026-10-08 02:10:14 +09:00
1 parent f11e636826
commit 4adf42cc4c
@@ -0,0 +1,16 @@
+#!/bin/sh
+set -eu
+
+repo_root="$(git rev-parse --show-toplevel)"
+script_path="$repo_root/screen-rtsp.ps1"
+config_path="$repo_root/config.ini"
+
+if ! command -v powershell.exe >/dev/null 2>&1; then
+    echo "ScreenRTSP: powershell.exe를 찾을 수 없어 config.ini 자동 기록 정보를 제거할 수 없습니다." >&2
+    exit 1
+fi
+
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$script_path" \
+    -ConfigPath "$config_path" -ResetManagedInfo >/dev/null
+git add -- "$config_path"
+
@@ -0,0 +1,11 @@
+#!/bin/sh
+set -eu
+
+managed_keys='CheckedAt|EnvironmentFingerprint|GPU|NvidiaNvencApi|NvidiaNvencRequiredApi|NvidiaNvencSupport|AmdAmfSupport|IntelQsvSupport|SelectedHardwareEncoder|FFmpegVersion|FFmpegBuild|FFmpegExecutableSha256|FFmpegDownloadSource|FFmpegArchiveSha256Verification|MediaMTXVersion|MediaMTXExecutableSha256|MediaMTXDownloadSource|MediaMTXArchiveSha256Verification|CompatibilityTest'
+
+if git show HEAD:config.ini 2>/dev/null | grep -E "^# (${managed_keys})=.+" >/dev/null 2>&1; then
+    echo "ScreenRTSP: HEAD의 config.ini에 실제 장치/설치 정보가 남아 있어 push를 중단합니다." >&2
+    echo "다시 커밋하면 pre-commit hook이 자동 기록 영역을 비웁니다." >&2
+    exit 1
+fi
+
@@ -16,7 +16,10 @@ RTSP는 `ddagrab` 기반 Desktop Duplication API로 화면과 마우스 커서
 - 전체 화면과 마우스 커서 포함
 - 모니터 연결, 해제, 좌표, 해상도, 회전, Primary 변경 감지
 - NVIDIA NVENC, AMD AMF, Intel QSV 자동 감지
- GPU 존재 여부와 FFmpeg 1프레임 초기화 시험을 함께 사용한 인코더 선택
+- GPU/드라이버를 매번 다시 읽고 각 인코더를 4초간 실제 인코딩한 뒤 H.264 IDR 주기를 검사해 선택
+- NVENC 요구 API와 드라이버 제공 API가 다르면 게시 해시가 있는 이전 호환 FFmpeg 후보를 시험
+- AMF를 포함한 모든 후보에 명시적 주기 IDR을 강제하고, 중간 접속 수신기의 첫 영상 수신을 검증
+- 환경이 바뀌면 단일 FFmpeg 2채널 2560×1440/30fps/채널당 8Mbps/AAC/11초 RTSP 최종 시험 수행
 - 기본 우선순위 `NVIDIA > AMD > Intel`, 실행 인자로 변경 가능
 - Windows Core Audio WASAPI loopback 기반 시스템 재생음 캡처
 - 실제 오디오 peak가 있는 출력 장치 우선 선택
@@ -39,8 +42,9 @@ RTSP는 `ddagrab` 기반 Desktop Duplication API로 화면과 마우스 커서
 - 로그인 트리거와 1분 간격 무기한 복구 트리거를 이용한 Watchdog 지속 복구
 - `config.ini` 기반 기능별 설정과 명령줄 override
 - 전체 오디오와 마이크 혼합을 각각 `1` 또는 `0`으로 활성화·비활성화
- FFmpeg와 MediaMTX 부재 시 HTTPS 다운로드, SHA-256 검증, 자동 설치
- 모니터·오디오·NIC·프로세스·절전 복구·설정·안전장치용 내장 시뮬레이션 42건
+- FFmpeg와 MediaMTX 부재 시 HTTPS 다운로드, 게시 SHA-256 검증, 후보 선검증 및 백업 가능한 안전 교체
+- `config.ini` 최상단에 비개인 환경·호환성 정보를 원자적으로 자동 기록
+- 모니터·오디오·NIC·프로세스·절전 복구·설정·안전장치용 내장 시뮬레이션 49건

 ## RTSP URL

@@ -78,6 +82,9 @@ WASAPI 출력 loopback worker → named pipe ─┐     ├─ FFmpeg 1개
 - `logs/watchdog.log`: watchdog 상태 로그
 - `logs/ffmpeg.log`: 모든 monitor 출력을 담당하는 단일 FFmpeg 로그
 - `logs/audio-loopback.log`: 단일 WASAPI loopback worker 오류 로그
+- `logs/compatibility-state.json`: 동일 환경의 무거운 2채널 최종 시험 성공 상태
+- `logs/dependency-evidence.json`: 다운로드 출처와 ZIP SHA-256 검증 이력
+- `logs/backups/`: 안전 교체 전 기존 실행 파일 백업

 실행 파일과 생성 파일은 저장소에 포함하지 않습니다. `Dependencies.AutoInstall=1`이면 실행할 때 없는 `ffmpeg.exe`와 `mediamtx.exe`를 스크립트 옆에 자동 설치합니다.

@@ -85,6 +92,19 @@ WASAPI 출력 loopback worker → named pipe ─┐     ├─ FFmpeg 1개

 기본 설정은 `screen-rtsp.ps1`과 같은 폴더의 `config.ini`에서 읽습니다.

+파일 최상단의 다음 표식 사이는 프로그램이 관리하는 설치 환경 정보입니다.
+
+```ini
+# >>> SCREENRTSP AUTO-MANAGED INSTALLATION ENVIRONMENT >>>
+# 이 부분은 실제 컴퓨터에서 실행한 후 자동 기록되며 사용자가 직접 수정하지 않습니다.
+# ...
+# <<< SCREENRTSP AUTO-MANAGED INSTALLATION ENVIRONMENT <<<
+```
+
+GPU 이름과 드라이버, NVENC API, AMF/QSV 시험 결과, 선택 인코더, FFmpeg/MediaMTX 버전·실행 파일 SHA-256·검증 출처·확인 시각이 기록됩니다. 모든 줄이 주석이므로 설정 파서가 읽지 않으며, 송출 판단은 이 기록이 아니라 실행 시 다시 수행한 실제 검사만 사용합니다. 사용자 이름, 컴퓨터 이름, IP, PnP 장치 ID, 토큰이나 인증 정보는 기록하지 않습니다.
+
+갱신은 같은 폴더의 임시 파일을 완성한 뒤 원자적으로 교체하므로 실패해도 기존 `config.ini`를 유지합니다. 표식 밖의 설정과 사용자 주석은 변경하지 않습니다.
+
 ```ini
 [Video]
 FrameRate=30
@@ -122,6 +142,8 @@ SignalThreshold=0.0005
 | `Dependencies` | `AutoInstall` | `1` | 실행 파일 부재 시 자동 설치 여부 |
 | `Dependencies` | `FFmpegUrl` | Gyan essentials ZIP | FFmpeg Windows ZIP 다운로드 주소 |
 | `Dependencies` | `FFmpegSha256Url` | Gyan SHA-256 | FFmpeg 게시 해시 주소 |
+| `Dependencies` | `FFmpegFallbackUrl` | BtbN 2026-05-31 n8.1 호환 빌드 | NVENC API 불일치 때만 시험할 Windows x64 후보 |
+| `Dependencies` | `FFmpegFallbackSha256Url` | 해당 Release `checksums.sha256` | 파일명과 일치하는 게시 해시 주소 |
 | `Dependencies` | `MediaMTXUrl` | v1.21.1 공식 ZIP | MediaMTX Windows amd64 ZIP 주소 |
 | `Dependencies` | `MediaMTXSha256` | v1.21.1 공식 해시 | MediaMTX ZIP 고정 SHA-256 |

@@ -137,11 +159,14 @@ INI를 해석한 최종 설정값만 확인하고 종료할 수도 있습니다.

 `ffmpeg.exe` 또는 `mediamtx.exe`가 없고 `Dependencies.AutoInstall=1`이면 다음 순서로 자동 설치합니다.

-1. HTTPS 주소만 허용하고 ZIP을 Windows 임시 폴더에 다운로드합니다.
-2. FFmpeg는 Gyan이 게시한 SHA-256을 받아 검증하고, MediaMTX는 공식 v1.21.1 Release의 고정 SHA-256을 검증합니다.
-3. 압축 안의 실행 파일만 `screen-rtsp.ps1` 옆으로 복사합니다.
-4. `ddagrab`, H.264 하드웨어 인코더, AAC 지원과 실행 버전을 확인합니다.
-5. 검증용 임시 폴더를 삭제합니다.
+1. 기존 실행 파일이 정상이면 유지하며 불필요하게 다운로드하지 않습니다.
+2. 필요할 때만 HTTPS 주소의 ZIP을 Windows 임시 폴더에 받습니다.
+3. FFmpeg는 배포자가 게시한 SHA-256을 파일명까지 대조하고, MediaMTX는 공식 v1.21.1 Release SHA-256을 검증합니다.
+4. 임시 폴더 안의 후보에서 `ddagrab`, `h264_nvenc`, `h264_amf`, `h264_qsv`, AAC와 DirectShow 지원을 확인합니다.
+5. 현재 설치 GPU별로 4초/120프레임 이상 인코딩하고, 디코딩 키프레임과 Annex-B NAL type 5가 GOP 30 기준으로 주기 생성되는지 검사합니다.
+6. NVIDIA 우선 환경에서 최신 빌드가 `Required NVENC API > Found API`로 실패하면 2026-05-31 BtbN n8.1 호환 후보를 동일한 절차와 2채널 RTSP 시험까지 통과시킨 뒤에만 채택합니다.
+7. 교체 직전 기존 실행 파일을 `logs/backups`에 보존하고 같은 볼륨에서 안전 교체합니다. 다운로드·해시·기능·인코딩 검증 중 하나라도 실패하면 기존 파일을 유지합니다.
+8. MediaMTX v1.21.1이 정상 실행되면 교체하지 않습니다.

 송출을 시작하지 않고 설치와 기능 확인만 먼저 수행할 수 있습니다.

@@ -149,14 +174,25 @@ INI를 해석한 최종 설정값만 확인하고 종료할 수도 있습니다.
 .\screen-rtsp.ps1 -InstallDependenciesOnly
 ```

+환경 변경 여부와 관계없이 2채널 최종 시험을 다시 수행하려면 다음처럼 실행합니다. 이미 Watchdog이 두 GPU 세션을 사용 중이면 시험 결과가 왜곡될 수 있으므로 먼저 자동 실행 작업을 완전히 중지한 상태에서 사용합니다.
+
+```powershell
+.\screen-rtsp.ps1 -InstallDependenciesOnly -ForceCompatibilityTest
+```
+
 자동 다운로드를 금지하려면 `AutoInstall=0`으로 바꿉니다. 이 경우 실행 파일이 없으면 오류를 표시하고 종료합니다. 자동 설치에는 인터넷 HTTPS 연결과 스크립트 폴더 쓰기 권한이 필요합니다.

+예를 들어 NVIDIA Quadro P6000 드라이버 582.70이 제공하는 NVENC API가 13.0이고 현재 FFmpeg 빌드가 13.1을 요구하면 로그에 `Required: 13.1 Found: 13.0`을 보존합니다. 이 경우 NVIDIA가 우선순위상 첫 GPU일 때만 13.1 헤더 도입 전의 BtbN 월별 보관 빌드를 내려받아 임시 위치에서 SHA-256, 기능, 4초 IDR, 2채널 RTSP 시험을 모두 수행합니다. 이전 빌드도 실패하면 설치하지 않고, 현재 FFmpeg에서 IDR 및 최종 수신 시험을 통과한 AMD AMF 또는 Intel QSV를 선택합니다.
+
 - FFmpeg Windows build: <https://www.gyan.dev/ffmpeg/builds/>
+- FFmpeg 공식 Windows 빌드 안내(Gyan/BtbN): <https://ffmpeg.org/download.html#build-windows>
+- NVENC API 13.1 최소 드라이버 안내: <https://github.com/FFmpeg/nv-codec-headers/blob/master/README>
+- NVENC API 13.0 호환 후보(BtbN monthly release): <https://github.com/BtbN/FFmpeg-Builds/releases/tag/autobuild-2026-05-31-13-22>
 - MediaMTX v1.21.1: <https://github.com/bluenviron/mediamtx/releases/tag/v1.21.1>

 ## 내장 시뮬레이션

-실제 송출 프로세스나 예약 작업을 만들지 않고 주요 판단 로직 42건을 검사합니다.
+실제 송출 프로세스나 예약 작업을 만들지 않고 주요 판단 로직 49건을 검사합니다. 자동 기록 블록의 파서 격리, 사용자 설정 보존, 중복 방지, 개인정보 키 배제와 GPU별 IDR 옵션도 포함됩니다.

 ```powershell
 .\screen-rtsp.ps1 -RunSimulationTests
@@ -166,14 +202,17 @@ INI를 해석한 최종 설정값만 확인하고 종료할 수도 있습니다.

 ## 처리 흐름

-1. FFmpeg와 MediaMTX가 없으면 설정에 따라 다운로드·검증·설치한 뒤, FFmpeg의 `ddagrab`과 H.264 하드웨어 인코더 포함 여부를 확인합니다.
-2. 설치된 GPU를 `NVIDIA > AMD > Intel` 순서로 찾고 각 인코더를 실제 1프레임으로 초기화합니다.
-3. 활성 모니터, IPv4 기본 경로 NIC, 활성 오디오 출력·입력 endpoint를 읽습니다.
-4. Core Audio peak가 감지된 출력 장치와 마이크를 우선하고, 신호가 없으면 Windows 기본 Multimedia 장치를 사용합니다.
-5. 모든 조건이 3초 동안 유지되면 WASAPI loopback worker 하나와 FFmpeg 하나를 시작합니다.
-6. 화면은 `ddagrab -> hwdownload -> BGRA -> 회전 보정 -> NV12 -> 하드웨어 H.264` 순서로 처리합니다.
-7. 시스템 소리는 named pipe, 마이크는 DirectShow로 FFmpeg에 입력됩니다. 두 소리를 `amix`한 뒤 `asplit`으로 각 RTSP 출력에 넣고 AAC로 인코딩합니다.
-8. 모니터, NIC, GPU, 오디오 장치 또는 자식 프로세스 상태가 바뀌면 전체 채널을 종료한 뒤 새 구성을 읽어 재시작합니다.
+1. FFmpeg와 MediaMTX가 없으면 HTTPS/SHA-256/후보 실행 검증 후 설치합니다.
+2. GPU와 드라이버를 다시 읽고 각 하드웨어 인코더로 4초 이상 실제 H.264를 생성해 주기 IDR을 검사합니다.
+3. NVIDIA NVENC API 불일치가 확인되면 호환 이전 빌드를 임시 폴더에서 먼저 검증합니다. 실패하면 기존 파일을 유지하고 IDR 검증을 통과한 AMF/QSV 후보로 넘어갑니다.
+4. 최초 실행이나 GPU·드라이버·FFmpeg·MediaMTX 변경 시 두 개의 1440p 시험 영상을 하나의 FFmpeg에서 RTSP로 publish하고 새 수신기 두 개로 11초간 실제 디코딩, IDR, FPS, 비트레이트와 AAC 트랙을 확인합니다.
+5. 검증 결과와 비개인 환경 정보를 `config.ini` 자동 기록 영역 및 watchdog 로그에 남깁니다.
+6. 활성 모니터, IPv4 기본 경로 NIC, 활성 오디오 출력·입력 endpoint를 읽습니다.
+7. Core Audio peak가 감지된 출력 장치와 마이크를 우선하고, 신호가 없으면 Windows 기본 Multimedia 장치를 사용합니다.
+8. 모든 조건이 3초 동안 유지되면 WASAPI loopback worker 하나와 FFmpeg 하나를 시작합니다.
+9. 화면은 `ddagrab -> hwdownload -> BGRA -> 회전 보정 -> NV12 -> 하드웨어 H.264` 순서로 처리합니다.
+10. 시스템 소리는 named pipe, 마이크는 DirectShow로 FFmpeg에 입력됩니다. 두 소리를 `amix`한 뒤 `asplit`으로 각 RTSP 출력에 넣고 AAC로 인코딩합니다.
+11. 모니터, NIC, GPU, 드라이버, 실행 파일, 오디오 장치 또는 자식 프로세스 상태가 바뀌면 전체 채널을 종료한 뒤 검증과 구성을 새로 읽어 재시작합니다.

 ## 설치 및 실행

@@ -292,3 +331,12 @@ GPU 우선순위를 바꾸는 예시:
 ## 저장소 정책

 FFmpeg와 MediaMTX 바이너리, 로그, 자동 생성 설정, 인증서와 키는 Git에 올리지 않습니다. 비밀번호나 토큰도 스크립트와 README에 기록하지 않습니다.
+
+실제 실행 후 `config.ini` 최상단에는 해당 PC의 GPU와 실행 파일 정보가 채워집니다. 저장소에는 표식과 안내 문구 및 빈 필드만 남겨야 하므로 `.githooks/pre-commit`이 커밋 직전에 자동 기록 영역만 비우고 다시 stage합니다. `pre-push`는 HEAD에 실제 값이 남아 있으면 push를 중단합니다. 스크립트를 Git 작업 폴더에서 한 번 실행하면 `core.hooksPath=.githooks`를 자동 설정하며, 수동 활성화와 수동 초기화 명령은 다음과 같습니다.
+
+```powershell
+.\screen-rtsp.ps1 -InstallGitHooks
+.\screen-rtsp.ps1 -ResetManagedInfo
+```
+
+이 초기화는 표식 사이만 교체하며 나머지 설정값과 사용자 주석을 보존합니다. `--no-verify`로 hook을 우회하지 마십시오.
@@ -1,4 +1,28 @@
-# ============================================================
+# >>> SCREENRTSP AUTO-MANAGED INSTALLATION ENVIRONMENT >>>
+# 이 부분은 실제 컴퓨터에서 실행한 후 자동 기록되며 사용자가 직접 수정하지 않습니다.
+# 설정값으로 해석되지 않으며 송출 동작을 결정하는 입력으로 사용되지 않습니다.
+# CheckedAt=
+# EnvironmentFingerprint=
+# GPU=
+# NvidiaNvencApi=
+# NvidiaNvencRequiredApi=
+# NvidiaNvencSupport=
+# AmdAmfSupport=
+# IntelQsvSupport=
+# SelectedHardwareEncoder=
+# FFmpegVersion=
+# FFmpegBuild=
+# FFmpegExecutableSha256=
+# FFmpegDownloadSource=
+# FFmpegArchiveSha256Verification=
+# MediaMTXVersion=
+# MediaMTXExecutableSha256=
+# MediaMTXDownloadSource=
+# MediaMTXArchiveSha256Verification=
+# CompatibilityTest=
+# <<< SCREENRTSP AUTO-MANAGED INSTALLATION ENVIRONMENT <<<
+
+# ============================================================
 # RTSP Watchdog 설정
 # ============================================================
 #
@@ -69,7 +93,7 @@ PollIntervalSec=1
 FrameRate=30
 Bitrate=8000k

-# 앞에 있는 GPU부터 실제 1프레임 인코더 초기화를 시험합니다.
+# 앞에 있는 GPU부터 3초 이상 실제 인코딩, 주기 IDR 및 2채널 RTSP 수신을 시험합니다.
 EncoderPriority=NVIDIA,AMD,Intel

 [Audio]
@@ -104,6 +128,11 @@ AutoInstall=1
 FFmpegUrl=https://www.gyan.dev/ffmpeg/builds/ffmpeg-release-essentials.zip
 FFmpegSha256Url=https://www.gyan.dev/ffmpeg/builds/ffmpeg-release-essentials.zip.sha256

+# 최신 빌드의 NVENC API가 현재 NVIDIA 드라이버보다 높을 때 시험할 2026-05-31 BtbN 호환 후보입니다.
+# FFmpeg 공식 다운로드 페이지가 안내하는 Windows 빌드이며 게시된 checksums.sha256을 검증합니다.
+FFmpegFallbackUrl=https://github.com/BtbN/FFmpeg-Builds/releases/download/autobuild-2026-05-31-13-22/ffmpeg-n8.1.1-9-g58d4114d36-win64-gpl-8.1.zip
+FFmpegFallbackSha256Url=https://github.com/BtbN/FFmpeg-Builds/releases/download/autobuild-2026-05-31-13-22/checksums.sha256
+
 # MediaMTX v1.21.1 공식 Windows amd64 ZIP과 GitHub Release SHA-256입니다.
 MediaMTXUrl=https://github.com/bluenviron/mediamtx/releases/download/v1.21.1/mediamtx_v1.21.1_windows_amd64.zip
 MediaMTXSha256=faa97974861eb75a68b5aa326c78e7e7a6f670b5ef191bace78e715130381f23