v0.4.36: suppress command/preload chat broadcast

Command-block and player usage no longer spams chat:
- Command feedback (videoPlace/videoDelete/videoMute) now uses
  sendSuccess(..., false) so only the executor sees it; command blocks
  write to their own output + server log instead of broadcasting to ops.
- Removed client-side [videopreload]/[videocache] notifyChat spam in
  VideoCache; download status remains in the client log via LOG.

Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>

.gitea/workflows/build.yml

@@ -17,7 +17,10 @@ jobs:
           java-version: 25
       - name: Build (MC 26.1.2)
         run: ./gradlew --no-daemon build
-      - uses: actions/upload-artifact@v4
+      # Gitea Actions runs on a GHES-compatible backend that does NOT support the
+      # @actions/artifact v2 protocol (upload-artifact@v4 → GHESNotSupportedError).
+      # v3 uses the v1 artifact API, which Gitea implements — so the run goes green.
+      - uses: actions/upload-artifact@v3
         with:
           name: video_player-mc26.1.2
           path: build/libs/*.jar

.gitignore

@@ -1,5 +1,6 @@
 .gradle/
 build/
+dist/
 out/
 .idea/
 .vscode/

README.md

@@ -3,7 +3,7 @@
 마인크래프트 안에서 임의의 동영상 URL을 벽·바닥·천장에 평면으로 재생하는 Fabric 모드.
 
 - 모드 ID: `video_player`
-- 현재 버전: **0.4.12**
+- 현재 버전: **0.4.35**
 - 마인크래프트 버전: **26.1.2**
 - 필요 Java: **25** (마인크래프트 26.x 가 요구함)
 
@@ -54,20 +54,20 @@ Fabric은 마인크래프트에 모드 기능을 추가해 주는 로더입니
 2. **video_player** (이 모드, 0.4.12 부터 JavaCV 가 jar 안에 포함됨)
    - 다운로드: https://git.tkrmagid.kr/tkrmagid/mc_video_player_mod/releases
    - 자신의 OS·CPU 에 맞는 jar **한 개** 만 받아서 `mods` 폴더에 넣으면 됩니다 (별도 JavaCV 설치 불필요):
-     - Windows 64bit: `video_player-windows-x86_64-0.4.12.jar` (~32MB)
+     - Windows 64bit: `video_player-windows-x86_64-0.4.35.jar` (~33MB)
-     - macOS Intel: `video_player-macosx-x86_64-0.4.12.jar` (~24MB)
+     - macOS Intel: `video_player-macosx-x86_64-0.4.35.jar` (~25MB)
-     - macOS Apple Silicon (M1/M2/M3/M4): `video_player-macosx-arm64-0.4.12.jar` (~21MB)
+     - macOS Apple Silicon (M1/M2/M3/M4): `video_player-macosx-arm64-0.4.35.jar` (~21MB)
-     - Linux 64bit: `video_player-linux-x86_64-0.4.12.jar` (~27MB)
+     - Linux 64bit: `video_player-linux-x86_64-0.4.35.jar` (~28MB)
    - 자기 OS 가 헷갈리면: Windows 는 거의 다 `windows-x86_64`, 인텔맥은 `macosx-x86_64`, 애플 실리콘 맥은 `macosx-arm64`, 리눅스는 `linux-x86_64`.
 
 이전 버전(`video_player-0.4.0.jar`, `0.4.2.jar`, `0.4.3.jar`, `0.3.x.jar` 등)이 mods 폴더에 남아있다면 **반드시 삭제**하세요. 두 개가 같이 있으면 마인크래프트가 충돌로 켜지지 않습니다. 0.4.7 이하에서 쓰던 JVM 인수(`-Xbootclasspath/a:...javacv...`) 도 0.4.12 부터는 **빼주세요** — 모드 jar 안에 같은 JavaCV 가 들어있어서 부트클래스패스의 것과 충돌해 검은 화면이 날 수 있습니다.
 
 ### STEP 5. 잘 설치됐는지 확인
 
-게임 안에서 채팅창에 `/videostick` 을 입력하세요. 정상이라면:
+게임 안에서 채팅창에 `/videoStick` 을 입력하세요 (대소문자 구분). 정상이라면:
 
 - 인벤토리에 **비디오 스틱** 아이템이 들어옵니다 (보라/검정 missing-texture 가 아니라 작대기 모양 아이콘).
-- 보라/검정 missing texture 가 나오면 **STEP 4** 에서 이전 버전 jar(`video_player-0.4.0.jar` / `0.4.1.jar` 등)가 mods 폴더에 같이 남아있는 경우입니다. 다 지우고 `0.4.12` 만 남기고 다시 시작하세요. (0.4.1 이하는 Fabric 26.1.2 model 로더가 unprefixed `item/generated` parent 를 거부해서 스틱 아이콘이 missing-model 큐브로 보입니다 — 0.4.2 에서 수정됨.)
+- 보라/검정 missing texture 가 나오면 **STEP 4** 에서 이전 버전 jar(`video_player-0.4.0.jar` / `0.4.1.jar` 등)가 mods 폴더에 같이 남아있는 경우입니다. 다 지우고 `0.4.35` 만 남기고 다시 시작하세요. (0.4.1 이하는 Fabric 26.1.2 model 로더가 unprefixed `item/generated` parent 를 거부해서 스틱 아이콘이 missing-model 큐브로 보입니다 — 0.4.2 에서 수정됨.)
 
 ---
 
@@ -93,75 +93,92 @@ Fabric은 마인크래프트에 모드 기능을 추가해 주는 로더입니
 
 ### 명령어
 
+명령어 이름은 **대소문자를 구분**합니다 (`/videoStick` 처럼 camelCase).
+
 | 명령 | 설명 |
 | --- | --- |
-| `/videostick` | 비디오 스틱 아이템을 인벤토리에 지급 |
+| `/videoStick` | 비디오 스틱 아이템을 인벤토리에 지급 (플레이어만) |
-| `/videoplace <pos> <facing> <w> <h> <url>` | 좌표에 영상 앵커를 즉시 배치 |
+| `/videoPlace <pos> <facing> <w> <h> <url-or-name>` | 좌표에 영상 앵커 배치 (볼륨 50%·음소거 해제). `url-or-name` 은 http(s) URL 또는 `/videoCache add` 로 등록한 이름 |
-| `/videodelete <pos>` | 좌표의 영상 앵커 제거 |
+| `/videoPlace <pos> <facing> <w> <h> <volume> <url-or-name>` | 위와 같지만 볼륨 지정: `0`~`100` (%) 또는 `-1`(음소거로 시작) |
-| `/videomute <pos> <on\|off>` | 영상의 음소거 켜고/끄기 |
+| `/videoDelete <pos>` | 좌표의 영상 앵커 제거 |
-| `/videopreload <url>` | URL 을 미리 받아 디스크 캐시에 저장 (자세한 내용은 아래) |
+| `/videoMute <pos> <on\|off>` | 영상의 음소거 켜고/끄기 |
+| `/videoCache add <name> <url>` | 자주 쓰는 URL 을 이름으로 등록 (서버 config 에 저장, 접속자에게 자동 프리로드) |
+| `/videoCache list` | 등록된 이름·URL 목록 표시 |
+| `/videoCache remove <name>` | 등록된 이름 1개 삭제 |
+| `/videoCache clear` | 등록된 이름 전체 삭제 |
 
-`/videoplace`, `/videodelete`, `/videomute`, `/videopreload` 는 기본적으로 OP(권한 레벨 2) 가 필요하므로 **커맨드 블럭에서도 그대로 호출 가능합니다**. 커맨드 블럭은 기본이 권한 레벨 2 라 별도 설정 없이 동작합니다.
+- `facing` 은 `north/south/east/west/up/down`, `w`·`h` 는 `1`~`32` 블록.
+- 모든 `/video*` 명령은 기본적으로 OP(권한 레벨 2) 가 필요하므로 **커맨드 블럭·콘솔에서도 그대로 호출 가능합니다**. 커맨드 블럭은 기본이 권한 레벨 2 라 별도 설정 없이 동작합니다. (0.4.31 부터 커맨드 블럭·콘솔·함수 등 비(非)플레이어 실행자는 `functionPermissionLevel` 게임룰을 건드리지 않아도 호출됩니다.)
+- `/videoStick` 만 플레이어 전용입니다(인벤토리에 아이템을 줘야 하므로).
 
-### `/videopreload` — 영상 미리 로딩 (스터터 제거)
+### 소리(오디오) 설정 (0.4.32+)
 
-스트리밍 URL 을 라이브로 받으면서 재생하면 네트워크가 잠깐 느려질 때 끊김이 생깁니다. `/videopreload <url>` 을 미리 한번 실행하면 클라이언트가 백그라운드에서 URL 을 통째로 다운로드해서 `.minecraft/video_player_cache/` 폴더에 저장해 두고, 같은 URL 로 영상이 재생될 때 인터넷이 아니라 그 로컬 파일을 사용합니다 (= 끊김 없음).
+영상 소리는 마인크래프트 **음량 슬라이더**의 영향을 받습니다. 0.4.32 부터 기본값은 **"주크박스/음반"(record)** 슬라이더입니다 — 영상은 미디어 재생이라 음악·효과음과 따로 조절하라고 이 채널을 씁니다. (마스터 슬라이더는 항상 위에서 한 번 더 곱해집니다.)
+
+어떤 슬라이더가 영상 소리를 제어할지는 `config/video_player.json` 의 `sound_category` 로 바꿀 수 있습니다 (클라이언트별 설정). 가능한 값: `master, music, record, weather, block, hostile, neutral, player, ambient, voice, ui`. 기본값은 `record` 이고, 잘못된 값을 적으면 경고 로그를 남기고 `record` 로 동작합니다.
+
+소리 크기는 **판때기 중앙**으로부터의 거리로 감쇠되며(16블록에서 0), `/videoMute <pos> <on|off>` 로 개별 영상을 음소거할 수 있습니다.
+
+### `/videoCache` — 영상 미리 로딩 (스터터 제거)
+
+스트리밍 URL 을 라이브로 받으면서 재생하면 네트워크가 잠깐 느려질 때 끊김이 생깁니다. `/videoCache add <name> <url>` 로 URL 을 이름과 함께 등록해 두면, 접속해 있는 모든 클라이언트가 백그라운드에서 그 URL 을 통째로 다운로드해 로컬 캐시에 저장하고, 같은 URL(또는 그 이름)로 영상이 재생될 때 인터넷이 아니라 로컬 파일을 사용합니다 (= 끊김 없음).
 
 ```
-/videopreload https://video.example.com/foo.mp4
+/videoCache add intro https://video.example.com/foo.mp4
+/videoPlace 10 64 10 north 4 3 intro          # 등록한 이름을 URL 자리에 그대로 사용
 ```
 
 특징:
 
-- **커맨드 블럭에서 사용 가능** — 예: 압력판 → 커맨드 블럭 `/videopreload <url>` 으로 트리거하면 플레이어가 영상 영역에 다가가기 전에 미리 다운로드 시작
+- **커맨드 블럭·콘솔에서 사용 가능** — 예: 서버 시작 시 함수로 `/videoCache add ...` 를 등록해 두면 접속자가 영상에 다가가기 전에 미리 다운로드가 시작됩니다
-- 명령은 서버에서 실행되지만, 다운로드는 각 **클라이언트**(접속해 있는 모든 플레이어)가 자기 PC 에 받습니다
+- 명령은 서버에서 실행되지만, 다운로드는 각 **클라이언트**(접속한 모든 플레이어)가 자기 PC 에 받습니다
-- 이미 받아둔 URL 은 재요청해도 다시 다운로드 안 함 (URL 의 SHA-256 으로 캐싱)
+- 등록한 이름은 서버 config(`config/video_player.json` 의 `cache_entries`)에 저장되어 **재시작 후에도 유지**되고, 새로 접속하는 플레이어에게도 자동으로 전달됩니다
-- 한 파일당 상한 512 MB
+- 이미 받아둔 URL 은 재요청해도 다시 다운로드하지 않습니다 (URL 의 SHA-256 으로 캐싱)
-- 캐시 폴더가 너무 커지면 직접 `.minecraft/video_player_cache/` 안의 파일을 삭제해도 됩니다 (그러면 다음 사용 시 다시 받아옴)
+- 한 영상당 / 전체 캐시 용량 상한은 config 의 `max_preload_mb` / `max_cache_mb` 로 정합니다 (아래 참고)
+- `/videoCache remove <name>` 하면 다운로드 중인 항목까지 취소되고 해당 캐시 파일이 삭제됩니다 (0.4.34)
+- 클라이언트 캐시는 **게임 종료 시 자동으로 비워집니다**. 등록 항목은 서버에 남아 있으므로 다음 접속 때 다시 받아옵니다 — 캐시 폴더를 수동으로 지울 필요가 없습니다
 
 > 영상 삭제 시 소리가 안 멎던 문제는 0.4.4 에서 수정되었습니다 (앵커 블록이 사라지면 디코더 / 오디오 라인을 즉시 강제 종료). 0.4.5 에서는 `BLOCK_ENTITY_UNLOAD` 이벤트가 누락되는 엣지케이스를 대비해 매 틱마다 BE 존재를 한 번 더 검증합니다.
 
-> 0.4.5 부터 다운로드 시작 / 완료 / 실패가 채팅창에 표시됩니다. 커맨드블럭으로 `/videopreload` 후 `/videoplace` 를 이어 실행할 때는 `[videopreload] 완료` 메시지를 본 뒤에 재생해야 로컬 파일에서 재생됩니다 (그 전에 재생하면 일반 스트리밍으로 떨어집니다).
+> 다운로드 시작 / 완료 / 실패는 `[videopreload]` 채팅 메시지로 표시됩니다. 커맨드블럭/함수로 `/videoCache add` 후 `/videoPlace` 를 이어 실행할 때는 `[videopreload] 완료` 메시지를 본 뒤에 재생해야 로컬 파일에서 재생됩니다 (그 전에 재생하면 일반 스트리밍으로 떨어집니다).
 
-> 0.4.5 부터 오디오 거리 감쇠가 **판때기 중앙**을 기준으로 계산됩니다. 예전엔 앵커 블록(보통 화면 모서리)을 기준으로 측정해서 큰 화면일수록 소리가 한쪽에서 들리는 느낌이었습니다.
+### 서버 config (`config/video_player.json`)
 
-### 서버 config 로 자동 프리로드 (0.4.6+)
+서버(싱글플레이는 통합 서버)에 모드를 넣고 한 번 실행하면 `config/video_player.json` 이 자동 생성됩니다. 기본 생성 내용:
-
-서버에 모드를 넣고 한 번 실행하면 `<서버폴더>/config/video_player.json` 가 자동 생성됩니다. 이 파일에 자주 쓰는 영상 URL 을 적어두면, 플레이어가 접속할 때마다 서버가 자동으로 그 URL 들의 프리로드 요청을 보냅니다 (= `/videopreload` 를 사람마다 친 것과 같음).
-
-기본 생성된 파일 예시:
 
 ```json
 {
-  "_comment": "preload_urls: HTTP(S) video URLs broadcast to every player on join. ...",
+  "_comment": "max_preload_mb: ... cache_entries: named entries managed by /videoCache add|list|remove.",
-  "preload_urls": []
+  "max_preload_mb": 2048,
+  "max_cache_mb": 750,
+  "render_distance_blocks": 128,
+  "sound_category": "record",
+  "preload_urls": [],
+  "cache_entries": []
 }
 ```
 
-사용 예시 — 인트로 영상과 BGM 영상을 모든 접속자가 미리 받도록:
+키 설명:
 
-```json
+- `max_preload_mb` — 클라이언트가 영상 **한 개**를 받을 때의 상한(MB). 초과하면 그 다운로드를 중단합니다. 기본 2048.
-{
+- `max_cache_mb` — 클라이언트 **전체 캐시 폴더**의 상한(MB). 기본 750.
-  "preload_urls": [
+- `render_distance_blocks` — 영상 앵커가 렌더링되는 최대 거리(블록). 기본 128.
-    "https://video.example.com/intro.mp4",
+- `sound_category` — 영상 오디오를 어느 음량 슬라이더로 제어할지 (위 "소리 설정" 참고). 기본 `record`.
-    "https://video.example.com/bgm-loop.webm"
+- `cache_entries` — `/videoCache add|list|remove` 로 관리되는 **이름 있는** 자동 프리로드 목록. 예: `[{ "name": "intro", "url": "https://video.example.com/intro.mp4" }]`. 직접 편집보다 명령어 사용을 권장합니다(명령어는 즉시 반영·접속자에게 즉시 브로드캐스트).
-  ]
+- `preload_urls` — 이름 없는 레거시 자동 프리로드 목록(하위호환). 접속 시 모든 플레이어가 받습니다. 각 URL 은 `http(s)://` 시작, 256자 이하.
-}
-```
 
 규칙:
 
-- 각 URL 은 `http://` 또는 `https://` 시작, 256자 이하 (그 외는 무시되고 서버 로그에 WARN)
+- `cache_entries` 는 명령어로 바꾸면 즉시 저장·반영됩니다. `preload_urls` 등 파일을 직접 수정한 경우엔 **서버 재시작** 이 필요합니다(파일은 시작 시 1회 로딩).
-- 파일 수정 후 적용하려면 **서버 재시작** 이 필요합니다 (config 는 시작 시 1회만 로딩)
+- 이미 캐시된 URL 은 다시 다운로드하지 않습니다 (SHA-256 캐시 키).
-- 접속한 플레이어 화면에는 `/videopreload` 와 동일한 `[videopreload] 다운로드 시작 / 완료` 채팅 메시지가 보입니다
+- 싱글플레이도 통합 서버의 `config/video_player.json` 에 동일하게 동작합니다.
-- 이미 캐시된 URL 은 다시 다운로드하지 않습니다 (SHA-256 캐시 키)
-- 싱글플레이는 자체적으로 통합 서버를 띄우므로, 통합 서버의 config 폴더(`<게임폴더>/config/video_player.json`)에도 같은 효과로 동작합니다
 
 ---
 
 ## 알려진 이슈
 
 - 영상 자리만 잡히고 검게 보이는 경우: 자신의 OS·CPU 와 다른 플랫폼의 jar 를 받았거나, 이전 버전(0.4.7 이하)의 `-Xbootclasspath/a:...javacv...` JVM 인수가 그대로 남아 있는 경우가 가장 흔합니다. 로그 파일(`.minecraft/logs/latest.log`)에서 `JavaCV not on classpath` WARN 또는 `UnsatisfiedLinkError... jnijavacpp` 메시지로 확인 가능합니다.
+- (0.4.33 에서 수정됨) 소리는 나오는데 화면만 검게 나오던 문제: 가로 픽셀 수가 16의 배수가 아닌 해상도의 영상(예: 1674×1080)에서 디코더 행 패딩(swscale linesize 정렬) 때문에 모든 프레임이 버려지던 버그였습니다. **0.4.33 이상**으로 올리면 해결됩니다.
 - 0.3.x 이하 버전에서 만든 영상은 새 버전(0.4.x) 에서 보이지 않으니 다시 배치해야 합니다.
 
 ---
@@ -172,7 +189,7 @@ Fabric은 마인크래프트에 모드 기능을 추가해 주는 로더입니
 ```sh
 JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew build
 ```
-산출물: `build/libs/video_player-0.4.12.jar` (~85KB)
+산출물: `build/libs/video_player-0.4.35.jar` (~106KB)
 
 플랫폼별 fat jar (JavaCV 1.5.13 + ffmpeg 8.0.1 네이티브 nested):
 ```sh
@@ -181,7 +198,7 @@ JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew clean build -Pplatform=li
 JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew clean build -Pplatform=macosx-x86_64
 JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew clean build -Pplatform=macosx-arm64
 ```
-산출물: `build/libs/video_player-<platform>-0.4.12.jar` (~21-32MB, jar 내부에 nested 로 javacv/javacpp/ffmpeg jar 5개 포함, Fabric loader 가 런타임에 classpath 로 풀어서 로딩)
+산출물: `build/libs/video_player-<platform>-0.4.35.jar` (~21-33MB, jar 내부에 nested 로 javacv/javacpp/ffmpeg jar 5개 포함, Fabric loader 가 런타임에 classpath 로 풀어서 로딩)
 
 JavaCV를 직접 의존성으로 가져오는 경우의 Maven 좌표:
 ```

gradle.properties

@@ -5,7 +5,7 @@ org.gradle.configuration-cache=false
 
 # Mod
 mod_id=video_player
-mod_version=0.4.14
+mod_version=0.4.36
 maven_group=com.ejclaw.videoplayer
 archives_base_name=video_player
 

src/main/java/com/ejclaw/videoplayer/VideoPlayerClient.java

@@ -1,7 +1,9 @@
 package com.ejclaw.videoplayer;
 
 import com.ejclaw.videoplayer.block.VideoAnchorBlockEntity;
+import com.ejclaw.videoplayer.client.MusicQuizClient;
 import com.ejclaw.videoplayer.client.net.ClientNetworking;
+import com.ejclaw.videoplayer.client.playback.VideoCache;
 import com.ejclaw.videoplayer.client.playback.VideoPlayback;
 import com.ejclaw.videoplayer.client.render.VideoAnchorRenderer;
 import com.ejclaw.videoplayer.item.VideoStickItem;
@@ -11,6 +13,7 @@ import net.fabricmc.api.ClientModInitializer;
 import net.fabricmc.api.EnvType;
 import net.fabricmc.api.Environment;
 import net.fabricmc.fabric.api.client.event.lifecycle.v1.ClientBlockEntityEvents;
+import net.fabricmc.fabric.api.client.event.lifecycle.v1.ClientLifecycleEvents;
 import net.fabricmc.fabric.api.client.event.lifecycle.v1.ClientTickEvents;
 import net.fabricmc.fabric.api.client.networking.v1.ClientPlayNetworking;
 import net.fabricmc.fabric.api.client.rendering.v1.BlockEntityRendererRegistry;
@@ -19,6 +22,7 @@ import net.fabricmc.fabric.api.event.player.AttackBlockCallback;
 import net.minecraft.client.Minecraft;
 import net.minecraft.client.player.LocalPlayer;
 import net.minecraft.core.BlockPos;
+import net.minecraft.sounds.SoundSource;
 import net.minecraft.world.InteractionResult;
 import net.minecraft.world.phys.Vec3;
 
@@ -28,6 +32,7 @@ public class VideoPlayerClient implements ClientModInitializer {
     @Override
     public void onInitializeClient() {
         ClientNetworking.register();
+        MusicQuizClient.register();
 
         BlockEntityRendererRegistry.register(
             VideoPlayerBlockEntities.VIDEO_ANCHOR,
@@ -79,6 +84,11 @@ public class VideoPlayerClient implements ClientModInitializer {
             }
         });
 
+        // Wipe video_player_cache/ on game exit so preloaded clips don't pile up across
+        // sessions. Cache entries are re-broadcast by the server on every JOIN, so a freshly
+        // started game will repopulate the cache automatically.
+        ClientLifecycleEvents.CLIENT_STOPPING.register(client -> VideoCache.wipeOnShutdown());
+
         VideoPlayerMod.LOG.info("[{}] client initialized", VideoPlayerMod.MOD_ID);
     }
 
@@ -87,17 +97,31 @@ public class VideoPlayerClient implements ClientModInitializer {
      * Distance is measured from the player's eye to the <em>panel center</em>, not the anchor
      * block corner — for a 4×4 panel the corner is ~2 blocks off from where the screen visually
      * sits, which made the audio feel like it was off to the side.
+     *
+     * <p>Gain is also gated by the Minecraft sound options so the in-game sliders work as
+     * expected: vanilla {@code SoundEngine.calculateVolume} multiplies by master × category, so
+     * we do the same. The category is configurable via {@code sound_category} in
+     * {@code config/video_player.json} (default {@link SoundSource#RECORDS} = the "Jukebox/Note
+     * Blocks" slider, since video playback is media). Master always gates on top; when the
+     * configured category is Master itself we don't square it. Result: dragging the configured
+     * category's slider in Options → Music &amp; Sounds attenuates video audio, and "Master"
+     * still gates everything.
      */
     private static void updateDistanceGains(Minecraft client) {
         LocalPlayer p = client.player;
         if (p == null || client.level == null) return;
         Vec3 eye = p.getEyePosition();
+        float masterVol = client.options.getSoundSourceVolume(SoundSource.MASTER);
+        SoundSource category = VideoPlayerConfig.soundCategory();
+        float categoryScale = (category == SoundSource.MASTER)
+            ? masterVol
+            : masterVol * client.options.getSoundSourceVolume(category);
         for (BlockPos pos : VideoPlayback.activePositions()) {
             if (!(client.level.getBlockEntity(pos) instanceof VideoAnchorBlockEntity be)) continue;
             Vec3 center = be.panelCenter();
             double d = center.distanceTo(eye);
             float attenuation = (float) Math.max(0.0, Math.min(1.0, 1.0 - d / 16.0));
-            float gain = be.isMuted() ? 0F : be.getVolume() * attenuation;
+            float gain = be.isMuted() ? 0F : be.getVolume() * attenuation * categoryScale;
             VideoPlayback.setGain(pos, gain);
         }
     }

src/main/java/com/ejclaw/videoplayer/VideoPlayerConfig.java

@@ -7,6 +7,7 @@ import com.google.gson.JsonElement;
 import com.google.gson.JsonObject;
 import com.google.gson.JsonParser;
 import net.fabricmc.loader.api.FabricLoader;
+import net.minecraft.sounds.SoundSource;
 
 import java.io.IOException;
 import java.nio.charset.StandardCharsets;
@@ -50,16 +51,29 @@ public final class VideoPlayerConfig {
     private static final String FILE_NAME = "video_player.json";
 
     /**
-     * Default per-video download cap in MB. Sized to comfortably fit ~50 short FHD clips:
+     * Default per-video download cap in MB. Sized to allow a single 4K short clip
-     * FHD H.264 at ~5 Mbps × 20 s ≈ 12.5 MB, so 50 × 15 MB ≈ 750 MB with headroom for
+     * (≈25 Mbps × 60 s ≈ 190 MB, with headroom for higher-bitrate sources). Per-video
-     * higher-bitrate sources.
+     * cap is intentionally separate from the total-cache cap below.
      */
-    private static final int DEFAULT_MAX_PRELOAD_MB = 750;
+    private static final int DEFAULT_MAX_PRELOAD_MB = 2048;
+    /**
+     * Default total-cache cap in MB. Sized to comfortably fit ~50 short FHD clips:
+     * FHD H.264 at ~5 Mbps × 20 s ≈ 12.5 MB, so 50 × 15 MB ≈ 750 MB with headroom.
+     */
+    private static final int DEFAULT_MAX_CACHE_MB = 750;
     /** Default render-distance cap for video anchors, in blocks. 128 = the legacy hard-coded value. */
     private static final int DEFAULT_RENDER_DISTANCE = 128;
+    /**
+     * Default Minecraft sound category the client uses to gate video audio. RECORDS = the
+     * "Jukebox/Note Blocks" (음반) slider — video playback is media, so it belongs there rather
+     * than on the player-sound slider. Master always gates on top of whatever category is set.
+     */
+    private static final SoundSource DEFAULT_SOUND_CATEGORY = SoundSource.RECORDS;
 
     private static volatile int    maxPreloadMb = DEFAULT_MAX_PRELOAD_MB;
+    private static volatile int    maxCacheMb   = DEFAULT_MAX_CACHE_MB;
     private static volatile int    renderDistanceBlocks = DEFAULT_RENDER_DISTANCE;
+    private static volatile SoundSource soundCategory = DEFAULT_SOUND_CATEGORY;
     private static volatile List<String> preloadUrls = Collections.emptyList();
     /** Insertion-ordered name → url. Mutated only under the class monitor. */
     private static final Map<String, String> CACHE_ENTRIES = new LinkedHashMap<>();
@@ -73,6 +87,9 @@ public final class VideoPlayerConfig {
                 VideoPlayerMod.LOG.info("[{}] created default config at {}",
                     VideoPlayerMod.MOD_ID, path);
                 maxPreloadMb = DEFAULT_MAX_PRELOAD_MB;
+                maxCacheMb = DEFAULT_MAX_CACHE_MB;
+                renderDistanceBlocks = DEFAULT_RENDER_DISTANCE;
+                soundCategory = DEFAULT_SOUND_CATEGORY;
                 preloadUrls = Collections.emptyList();
                 CACHE_ENTRIES.clear();
                 return;
@@ -80,26 +97,63 @@ public final class VideoPlayerConfig {
             String raw = Files.readString(path, StandardCharsets.UTF_8);
             JsonObject json = JsonParser.parseString(raw).getAsJsonObject();
 
-            // max_preload_mb (sanity-clamped to [16, 16384] so a typo can't brick a client)
+            // Track whether any expected key was missing; if so, we rewrite the file at the
+            // end so users don't have to delete their config to pick up new options.
+            boolean augmented = false;
+
+            // max_preload_mb (per-video cap, sanity-clamped to [16, 16384])
             int cap = DEFAULT_MAX_PRELOAD_MB;
             if (json.has("max_preload_mb") && json.get("max_preload_mb").isJsonPrimitive()
                     && json.get("max_preload_mb").getAsJsonPrimitive().isNumber()) {
                 cap = json.get("max_preload_mb").getAsInt();
+            } else {
+                augmented = true;
             }
             if (cap < 16) cap = 16;
             if (cap > 16384) cap = 16384;
             maxPreloadMb = cap;
 
+            // max_cache_mb (total-cache cap, sanity-clamped to [16, 65536])
+            int total = DEFAULT_MAX_CACHE_MB;
+            if (json.has("max_cache_mb") && json.get("max_cache_mb").isJsonPrimitive()
+                    && json.get("max_cache_mb").getAsJsonPrimitive().isNumber()) {
+                total = json.get("max_cache_mb").getAsInt();
+            } else {
+                augmented = true;
+            }
+            if (total < 16) total = 16;
+            if (total > 65536) total = 65536;
+            maxCacheMb = total;
+
             // render_distance_blocks (sanity-clamped to [16, 2048])
             int rd = DEFAULT_RENDER_DISTANCE;
             if (json.has("render_distance_blocks") && json.get("render_distance_blocks").isJsonPrimitive()
                     && json.get("render_distance_blocks").getAsJsonPrimitive().isNumber()) {
                 rd = json.get("render_distance_blocks").getAsInt();
+            } else {
+                augmented = true;
             }
             if (rd < 16)   rd = 16;
             if (rd > 2048) rd = 2048;
             renderDistanceBlocks = rd;
 
+            // sound_category (client uses this to pick which volume slider gates video audio)
+            SoundSource cat = DEFAULT_SOUND_CATEGORY;
+            if (json.has("sound_category") && json.get("sound_category").isJsonPrimitive()
+                    && json.get("sound_category").getAsJsonPrimitive().isString()) {
+                SoundSource parsed = parseSoundSource(json.get("sound_category").getAsString());
+                if (parsed != null) {
+                    cat = parsed;
+                } else {
+                    VideoPlayerMod.LOG.warn("[{}] config: unknown sound_category '{}' — using '{}'",
+                        VideoPlayerMod.MOD_ID, json.get("sound_category").getAsString(),
+                        DEFAULT_SOUND_CATEGORY.getName());
+                }
+            } else {
+                augmented = true;
+            }
+            soundCategory = cat;
+
             // preload_urls (legacy)
             List<String> urls = new ArrayList<>();
             if (json.has("preload_urls") && json.get("preload_urls").isJsonArray()) {
@@ -134,18 +188,41 @@ public final class VideoPlayerConfig {
             }
 
             VideoPlayerMod.LOG.info(
-                "[{}] config loaded: cap={} MB, render={} blocks, preload_urls={}, cache_entries={}",
+                "[{}] config loaded: per-video={} MB, total-cache={} MB, render={} blocks, "
-                VideoPlayerMod.MOD_ID, maxPreloadMb, renderDistanceBlocks, urls.size(), CACHE_ENTRIES.size());
+                    + "sound_category={}, preload_urls={}, cache_entries={}",
+                VideoPlayerMod.MOD_ID, maxPreloadMb, maxCacheMb, renderDistanceBlocks,
+                soundCategory.getName(), urls.size(), CACHE_ENTRIES.size());
+
+            // Auto-augment: rewrite the file once so missing keys appear after a mod update.
+            if (augmented) {
+                VideoPlayerMod.LOG.info(
+                    "[{}] config missing one or more keys — rewriting with defaults filled in",
+                    VideoPlayerMod.MOD_ID);
+                save();
+            }
         } catch (Throwable t) {
             VideoPlayerMod.LOG.warn("[{}] failed to read config {}: {} — using defaults",
                 VideoPlayerMod.MOD_ID, path, t.toString());
             maxPreloadMb = DEFAULT_MAX_PRELOAD_MB;
+            maxCacheMb = DEFAULT_MAX_CACHE_MB;
             renderDistanceBlocks = DEFAULT_RENDER_DISTANCE;
+            soundCategory = DEFAULT_SOUND_CATEGORY;
             preloadUrls = Collections.emptyList();
             CACHE_ENTRIES.clear();
         }
     }
 
+    /** Match a config string against {@link SoundSource#getName()} (case-insensitive). Null = no match. */
+    private static SoundSource parseSoundSource(String s) {
+        if (s == null) return null;
+        String t = s.trim();
+        if (t.isEmpty()) return null;
+        for (SoundSource src : SoundSource.values()) {
+            if (src.getName().equalsIgnoreCase(t)) return src;
+        }
+        return null;
+    }
+
     // -- accessors ---------------------------------------------------------------------------
 
     /** Hard cap on a single client-side video download, in MB. */
@@ -154,9 +231,21 @@ public final class VideoPlayerConfig {
     /** Same value in bytes. */
     public static long maxPreloadBytes() { return (long) maxPreloadMb * 1024L * 1024L; }
 
+    /** Hard cap on the client-side total cache directory, in MB. */
+    public static int maxCacheMb() { return maxCacheMb; }
+
+    /** Same value in bytes. */
+    public static long maxCacheBytes() { return (long) maxCacheMb * 1024L * 1024L; }
+
     /** Anchor BE view-distance cap, in blocks. */
     public static int renderDistanceBlocks() { return renderDistanceBlocks; }
 
+    /**
+     * Minecraft sound category the client gates video audio with (default {@link SoundSource#RECORDS}).
+     * Read client-side from the local config; not pushed from the server.
+     */
+    public static SoundSource soundCategory() { return soundCategory; }
+
     /** Legacy un-named preload list (still pushed at join). Never null. */
     public static List<String> preloadUrls() { return preloadUrls; }
 
@@ -234,11 +323,17 @@ public final class VideoPlayerConfig {
         JsonObject root = new JsonObject();
         root.addProperty("_comment",
             "max_preload_mb: per-video download cap (each client). "
+                + "max_cache_mb: total cache directory cap (each client). "
                 + "render_distance_blocks: max distance at which a video anchor still renders. "
+                + "sound_category: which Minecraft volume slider gates video audio (client-side). "
+                + "One of: master, music, record, weather, block, hostile, neutral, player, "
+                + "ambient, voice, ui. Default 'record' = the Jukebox/Note Blocks slider. "
                 + "preload_urls: HTTP(S) videos auto-pushed to every player on join (no name). "
                 + "cache_entries: named entries managed by /videoCache add|list|remove.");
         root.addProperty("max_preload_mb", DEFAULT_MAX_PRELOAD_MB);
+        root.addProperty("max_cache_mb", DEFAULT_MAX_CACHE_MB);
         root.addProperty("render_distance_blocks", DEFAULT_RENDER_DISTANCE);
+        root.addProperty("sound_category", DEFAULT_SOUND_CATEGORY.getName());
         root.add("preload_urls", new JsonArray());
         root.add("cache_entries", new JsonArray());
         Gson gson = new GsonBuilder().setPrettyPrinting().disableHtmlEscaping().create();
@@ -253,11 +348,17 @@ public final class VideoPlayerConfig {
             JsonObject root = new JsonObject();
             root.addProperty("_comment",
                 "max_preload_mb: per-video download cap (each client). "
+                    + "max_cache_mb: total cache directory cap (each client). "
                     + "render_distance_blocks: max distance at which a video anchor still renders. "
+                    + "sound_category: which Minecraft volume slider gates video audio (client-side). "
+                    + "One of: master, music, record, weather, block, hostile, neutral, player, "
+                    + "ambient, voice, ui. Default 'record' = the Jukebox/Note Blocks slider. "
                     + "preload_urls: legacy un-named auto-preload list. "
                     + "cache_entries: managed by /videoCache add|list|remove.");
             root.addProperty("max_preload_mb", maxPreloadMb);
+            root.addProperty("max_cache_mb", maxCacheMb);
             root.addProperty("render_distance_blocks", renderDistanceBlocks);
+            root.addProperty("sound_category", soundCategory.getName());
             JsonArray legacyArr = new JsonArray();
             for (String u : preloadUrls) legacyArr.add(u);
             root.add("preload_urls", legacyArr);

src/main/java/com/ejclaw/videoplayer/VideoPlayerMod.java

@@ -8,6 +8,7 @@ import com.ejclaw.videoplayer.command.VideoStickCommand;
 import com.ejclaw.videoplayer.net.CachePolicyPayload;
 import com.ejclaw.videoplayer.net.PreloadPayload;
 import com.ejclaw.videoplayer.net.VideoPlayerNetwork;
+import com.ejclaw.videoplayer.server.MusicQuizPresence;
 import com.ejclaw.videoplayer.registry.VideoPlayerBlockEntities;
 import com.ejclaw.videoplayer.registry.VideoPlayerBlocks;
 import com.ejclaw.videoplayer.registry.VideoPlayerItems;
@@ -30,6 +31,7 @@ public class VideoPlayerMod implements ModInitializer {
 
         VideoPlayerNetwork.registerPayloadTypes();
         VideoPlayerNetwork.registerServerReceivers();
+        MusicQuizPresence.register();
 
         VideoPlayerConfig.load();
 
@@ -50,6 +52,7 @@ public class VideoPlayerMod implements ModInitializer {
             var player = handler.getPlayer();
             ServerPlayNetworking.send(player, new CachePolicyPayload(
                 VideoPlayerConfig.maxPreloadBytes(),
+                VideoPlayerConfig.maxCacheBytes(),
                 VideoPlayerConfig.renderDistanceBlocks()));
 
             int sent = 0;

src/main/java/com/ejclaw/videoplayer/block/VideoAnchorBlockEntity.java

@@ -3,7 +3,11 @@ package com.ejclaw.videoplayer.block;
 import com.ejclaw.videoplayer.registry.VideoPlayerBlockEntities;
 import net.minecraft.core.BlockPos;
 import net.minecraft.core.Direction;
+import net.minecraft.core.HolderLookup;
 import net.minecraft.nbt.CompoundTag;
+import net.minecraft.network.protocol.Packet;
+import net.minecraft.network.protocol.game.ClientGamePacketListener;
+import net.minecraft.network.protocol.game.ClientboundBlockEntityDataPacket;
 import net.minecraft.world.level.block.entity.BlockEntity;
 import net.minecraft.world.level.block.state.BlockState;
 import net.minecraft.world.level.storage.ValueInput;
@@ -123,6 +127,35 @@ public class VideoAnchorBlockEntity extends BlockEntity {
         out.putBoolean("autoplay", autoplay);
     }
 
+    /**
+     * Vanilla chunk-load BE sync. The base implementation returns an empty tag, which means
+     * when a client first sees this BE (chunk loads or player walks into range) it gets default
+     * values — url="" in particular makes the renderer no-op and the panel appears invisible.
+     *
+     * <p>Returning {@link #toNbt()} here carries the custom fields in the vanilla packet, so
+     * we don't depend on the {@code SyncAnchorPayload} arriving before the chunk's block-update
+     * packet (there's a race: {@code level.setBlock} queues a deferred chunk broadcast while
+     * {@code ServerPlayNetworking.send} writes immediately; if the payload wins, the client
+     * drops it because the BE doesn't exist yet, then the chunk packet creates the BE with
+     * defaults). It also fixes "player walks far away and comes back" — that path has no
+     * SyncAnchorPayload at all, just vanilla chunk re-sync.
+     */
+    @Override
+    public CompoundTag getUpdateTag(HolderLookup.Provider provider) {
+        return toNbt();
+    }
+
+    /**
+     * Triggers a {@link ClientboundBlockEntityDataPacket} whenever the chunk tracker decides
+     * this BE needs to push an update. Default implementation returns {@code null} (no packet
+     * sent on BE change). Combined with {@link #getUpdateTag} above, every BE-state change a
+     * client sees carries the full config.
+     */
+    @Override
+    public Packet<ClientGamePacketListener> getUpdatePacket() {
+        return ClientboundBlockEntityDataPacket.create(this);
+    }
+
     @Override
     protected void loadAdditional(ValueInput in) {
         super.loadAdditional(in);

src/main/java/com/ejclaw/videoplayer/client/MusicQuizClient.java

@@ -0,0 +1,56 @@
+package com.ejclaw.videoplayer.client;
+
+import com.ejclaw.videoplayer.net.MqHelloPayload;
+import net.fabricmc.api.EnvType;
+import net.fabricmc.api.Environment;
+import net.fabricmc.fabric.api.client.event.lifecycle.v1.ClientTickEvents;
+import net.fabricmc.fabric.api.client.networking.v1.ClientPlayConnectionEvents;
+import net.fabricmc.fabric.api.client.networking.v1.ClientPlayNetworking;
+
+/**
+ * Client side of the {@code music_quiz} datapack handshake
+ * ({@code docs/mc_video_player_mod_integration.md}). Sends one {@link MqHelloPayload}
+ * on JOIN, then repeats every 100 client ticks (~5 s at 20 tps).
+ *
+ * <p>The periodic resend is <em>mandatory</em>: the datapack's
+ * {@code mq:players/login} resets the per-player score to 0 the moment the player
+ * passes the spawn dialog. The single JOIN-time send can land before that reset,
+ * leaving the score at 0 and breaking the {@code mq:commands/start} guard. With a
+ * 5-second resend, the score is restored to 1 within at most one cycle.
+ */
+@Environment(EnvType.CLIENT)
+public final class MusicQuizClient {
+    private MusicQuizClient() {}
+
+    /** ~5 s at 20 tps. Spec recommends ≤5 s; tighter is fine but unnecessary. */
+    private static final int RESEND_INTERVAL_TICKS = 100;
+
+    private static int tickCounter = 0;
+
+    public static void register() {
+        ClientPlayConnectionEvents.JOIN.register((handler, sender, client) ->
+            send());
+
+        ClientTickEvents.END_CLIENT_TICK.register(client -> {
+            // Gate on world presence — when the player isn't in-game, level is null and the
+            // counter resets so the next session starts fresh instead of firing immediately.
+            if (client.level == null) {
+                tickCounter = 0;
+                return;
+            }
+            tickCounter++;
+            if (tickCounter >= RESEND_INTERVAL_TICKS) {
+                tickCounter = 0;
+                send();
+            }
+        });
+    }
+
+    private static void send() {
+        // ClientPlayNetworking.send no-ops when the server hasn't registered the payload
+        // type (e.g. vanilla server or server without this mod) — safe to call blindly.
+        if (ClientPlayNetworking.canSend(MqHelloPayload.TYPE)) {
+            ClientPlayNetworking.send(new MqHelloPayload(MqHelloPayload.CURRENT_VERSION));
+        }
+    }
+}

src/main/java/com/ejclaw/videoplayer/client/net/ClientNetworking.java

@@ -6,6 +6,7 @@ import com.ejclaw.videoplayer.client.gui.VideoConfigScreen;
 import com.ejclaw.videoplayer.client.playback.VideoCache;
 import com.ejclaw.videoplayer.client.playback.VideoPlayback;
 import com.ejclaw.videoplayer.net.CachePolicyPayload;
+import com.ejclaw.videoplayer.net.ClearCachePayload;
 import com.ejclaw.videoplayer.net.DeleteCachePayload;
 import com.ejclaw.videoplayer.net.OpenScreenPayload;
 import com.ejclaw.videoplayer.net.PreloadPayload;
@@ -44,10 +45,12 @@ public final class ClientNetworking {
             VideoCache.preload(payload.url());
         });
 
-        // Server tells us the per-video download cap (bytes). Must arrive before PreloadPayload
+        // Server tells us the per-video and total-cache download caps (bytes). Must arrive
-        // (the server sends policy first on JOIN), so we don't accidentally use the stale default.
+        // before PreloadPayload (server sends policy first on JOIN) so we don't use stale
+        // defaults.
         ClientPlayNetworking.registerGlobalReceiver(CachePolicyPayload.TYPE, (payload, context) -> {
-            VideoCache.setMaxBytes(payload.maxBytes());
+            VideoCache.setMaxBytes(payload.maxPerVideoBytes());
+            VideoCache.setMaxCacheBytes(payload.maxCacheBytes());
             ClientPolicy.setRenderDistanceBlocks(payload.renderDistanceBlocks());
         });
 
@@ -55,5 +58,10 @@ public final class ClientNetworking {
         ClientPlayNetworking.registerGlobalReceiver(DeleteCachePayload.TYPE, (payload, context) -> {
             VideoCache.purge(payload.url());
         });
+
+        // /videoCache clear — wipe the entire client cache directory.
+        ClientPlayNetworking.registerGlobalReceiver(ClearCachePayload.TYPE, (payload, context) -> {
+            VideoCache.clearAll();
+        });
     }
 }

src/main/java/com/ejclaw/videoplayer/client/playback/JavaCvBackend.java

@@ -180,27 +180,24 @@ public class JavaCvBackend implements VideoBackend {
         // stale srcAddr — closing the grabber there frees the av_frame plane and the next
         // memcpy crashes inside StubRoutines::jbyte_disjoint_arraycopy (exactly the 4K-delete
         // crash dump we saw). So the safe rule is: only the decoder thread touches the
-        // grabber. External stop signals `running=false`, stops the audio line, interrupts the
+        // grabber. External stop signals `running=false`, stops the audio line, interrupts
-        // worker, and joins briefly; the worker's own `finally` calls grabber.close(). Inside
+        // the worker, and returns immediately; the worker's own `finally` calls
-        // the loop, grab() unblocks via the rw_timeout/timeout options (3 s, set in runLoop)
+        // grabber.close() whenever grab()/start() eventually returns.
-        // even on a stuck HTTP read, so the join below normally returns within a frame.
+        //
+        // We deliberately do NOT join the worker. close() runs on the client tick thread (via
+        // VideoPlayback.tick → Entry.close), and the worker can spend several seconds inside
+        // the native FFmpeg probe at the top of runLoop — probesize=8 MB and
+        // analyzeduration=2 s do not honor the `running` flag and Thread.interrupt() doesn't
+        // unblock native I/O. A bounded join() there (the old 2 s) is exactly the "place then
+        // immediately delete freezes the game for a moment" symptom: the worker hasn't
+        // entered the grab() loop yet, so flipping running=false has no effect on it until
+        // start() returns. The worker is a daemon, the audio line is already silenced above,
+        // and Entry has been removed from the active map by the caller — nothing observable
+        // depends on the grabber having been closed before this method returns.
         Thread t = worker;
         worker = null;
         if (t != null) {
             t.interrupt();
-            try {
-                t.join(2000);
-            } catch (InterruptedException ie) {
-                Thread.currentThread().interrupt();
-            }
-            if (t.isAlive()) {
-                // Worker still blocked in native grab() — let it finish on its own. Its
-                // finally still closes the grabber when grab() eventually returns / throws.
-                // No native pointers leak in the meantime because we don't touch them here.
-                VideoPlayerMod.LOG.warn(
-                    "[{}] decoder did not exit within 2 s of stop; orphaning until next grab() returns",
-                    VideoPlayerMod.MOD_ID);
-            }
         }
         ready = false;
     }
@@ -279,6 +276,14 @@ public class JavaCvBackend implements VideoBackend {
             Class<?> frameCls    = Class.forName(FRAME_CLASS);
             Field imageField     = frameCls.getField("image");
             Field samplesField   = frameCls.getField("samples");
+            // Row stride (bytes) of frame.image[0]. swscale aligns the RGBA linesize to a SIMD
+            // boundary (32/64 B), so for any width whose width*4 isn't already aligned the plane
+            // is padded: e.g. 1674-wide → linesize 6720 instead of 6696. We read this to strip
+            // the padding row-by-row; resolved defensively so a Frame without the field just
+            // falls back to deriving the stride from the buffer size below.
+            Field strideField;
+            try { strideField = frameCls.getField("imageStride"); }
+            catch (Throwable t) { strideField = null; }
             // Java2DFrameConverter is no longer used now that we read RGBA bytes directly,
             // but we still resolve its class so a future code path could fall back to it if a
             // grabber refuses setPixelFormat. Keep the lookup defensive.
@@ -326,26 +331,40 @@ public class JavaCvBackend implements VideoBackend {
                     // primary memory-churn problem; 0.4.10 fixed that; 0.4.11 adds the ring on
                     // top to absorb the burst-then-stall caused by SourceDataLine backpressure
                     // pacing only at audio-buffer granularity.
-                    int need = src.remaining();
+                    // The destination texture is tightly packed: one frame = width*height*4
-                    // Reviewer-mandated sanity bounds: memCopy is a raw native copy with no
+                    // bytes with no row padding (consumeFrame copies ringBytes[idx] straight
-                    // fence against overrun. Validate against (a) the source buffer's own
+                    // into a w*h*4 GPU texture and rejects anything larger). swscale, however,
-                    // capacity (so a corrupt plane can't read past it) and (b) the expected
+                    // hands us an RGBA plane whose linesize is SIMD-aligned, so for any width
-                    // RGBA frame size (width*height*4) (so an unexpectedly oversized plane
+                    // where width*4 isn't a multiple of the alignment the source rows carry
-                    // can't smash the dst slot we'll allocate). If either fails, skip this
+                    // trailing padding (e.g. 1674-wide → 6720 B/row vs the 6696 B we want).
-                    // frame and continue — the next grab() will give us a fresh one.
+                    // Copying the padded buffer verbatim both overruns the tight dst slot and
-                    int expected = width * height * 4;
+                    // shears the image; we must strip the pad row-by-row.
-                    if (need > src.capacity()) {
+                    int rowBytes = width * 4;            // bytes of real pixels per row
-                        VideoPlayerMod.LOG.warn("[{}] frame overruns source capacity (need={}, cap={}); skipping",
+                    int dstBytes = rowBytes * height;    // tightly-packed frame size
-                            VideoPlayerMod.MOD_ID, need, src.capacity());
+                    // Source row stride: prefer Frame.imageStride (authoritative), else derive
-                        need = 0;
+                    // it from the buffer size. Guard against a stride smaller than a full row
-                    } else if (need > expected) {
+                    // (bogus field) by falling back to the tight rowBytes.
-                        VideoPlayerMod.LOG.warn("[{}] frame larger than expected RGBA size (need={}, expected={}); skipping",
+                    int strideBytes = rowBytes;
-                            VideoPlayerMod.MOD_ID, need, expected);
+                    if (strideField != null) {
-                        need = 0;
+                        try {
+                            int s = strideField.getInt(frame);
+                            if (s >= rowBytes) strideBytes = s;
+                        } catch (Throwable ignored) {}
+                    } else if (height > 0) {
+                        int s = src.remaining() / height;
+                        if (s >= rowBytes) strideBytes = s;
                     }
-                    if (need > 0) {
+                    // Sanity bound: the strided read must stay within the source buffer. memCopy
+                    // is a raw native copy with no overrun fence, so if the plane is smaller than
+                    // stride*height (corrupt/truncated) skip this frame and grab a fresh one.
+                    boolean ok = dstBytes > 0 && (long) strideBytes * height <= src.capacity();
+                    if (!ok && dstBytes > 0) {
+                        VideoPlayerMod.LOG.warn("[{}] frame plane too small (stride={}, h={}, cap={}); skipping",
+                            VideoPlayerMod.MOD_ID, strideBytes, height, src.capacity());
+                    }
+                    if (ok) {
                         int srcPos = src.position();
-                        long srcAddr = MemoryUtil.memAddress(src) + srcPos;
+                        long srcBase = MemoryUtil.memAddress(src) + srcPos;
                         synchronized (frameLock) {
                             // Recheck shutdown inside the lock: stopWorker() flipped running=false
                             // before signaling, so worker is the only writer here and grabber.close()
@@ -353,12 +372,21 @@ public class JavaCvBackend implements VideoBackend {
                             // the contract obvious to future readers.
                             if (!running.get() || closed) break;
                             int idx = ringTail;
-                            if (ringBufs[idx] == null || ringBufs[idx].capacity() < need) {
+                            if (ringBufs[idx] == null || ringBufs[idx].capacity() < dstBytes) {
-                                ringBufs[idx] = ByteBuffer.allocateDirect(need).order(ByteOrder.nativeOrder());
+                                ringBufs[idx] = ByteBuffer.allocateDirect(dstBytes).order(ByteOrder.nativeOrder());
                             }
-                            long dstAddr = MemoryUtil.memAddress(ringBufs[idx]);
+                            long dstBase = MemoryUtil.memAddress(ringBufs[idx]);
-                            MemoryUtil.memCopy(srcAddr, dstAddr, need);
+                            if (strideBytes == rowBytes) {
-                            ringBytes[idx] = need;
+                                MemoryUtil.memCopy(srcBase, dstBase, dstBytes);
+                            } else {
+                                // Strip swscale row padding: copy only the real pixels per row.
+                                for (int y = 0; y < height; y++) {
+                                    MemoryUtil.memCopy(srcBase + (long) y * strideBytes,
+                                                       dstBase + (long) y * rowBytes,
+                                                       rowBytes);
+                                }
+                            }
+                            ringBytes[idx] = dstBytes;
                             ringTail = (idx + 1) % FRAME_RING_SLOTS;
                             if (ringCount < FRAME_RING_SLOTS) {
                                 ringCount++;

src/main/java/com/ejclaw/videoplayer/client/playback/VideoCache.java

@@ -3,9 +3,7 @@ package com.ejclaw.videoplayer.client.playback;
 import com.ejclaw.videoplayer.VideoPlayerMod;
 import net.fabricmc.api.EnvType;
 import net.fabricmc.api.Environment;
-import net.minecraft.ChatFormatting;
 import net.minecraft.client.Minecraft;
-import net.minecraft.network.chat.Component;
 
 import java.io.InputStream;
 import java.io.OutputStream;
@@ -20,6 +18,9 @@ import java.util.HashSet;
 import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.atomic.AtomicLong;
 
 /**
  * Client-side disk cache for preloaded HTTP video URLs. Driven by the {@code /videopreload}
@@ -38,28 +39,86 @@ public final class VideoCache {
 
     /** url → local absolute path of the fully-downloaded cache file. */
     private static final Map<String, Path> READY = new ConcurrentHashMap<>();
-    /** urls whose download is currently in flight. */
+    /** urls whose download is currently queued or in flight. */
     private static final Set<String> IN_FLIGHT = ConcurrentHashMap.newKeySet();
+    /**
+     * Monotonic cache-generation counter. {@link #clearAll()} bumps this; every download
+     * captures the value at submit time and bails (deletes its {@code .part} without
+     * publishing) if the epoch has moved since. This is the cancellation channel for the
+     * in-flight download — without it, {@code clearAll} only wipes already-finalized files
+     * while the running download keeps writing and re-publishes one entry post-clear.
+     */
+    private static final AtomicLong CACHE_EPOCH = new AtomicLong(0);
 
     /**
-     * Hard ceiling on a single preload, in bytes. Default 750 MB sized to fit ~50 short FHD
+     * Per-URL cancellation channel for {@link #purge(String)}. The global {@link #CACHE_EPOCH}
-     * clips; overridden per-session by {@link com.ejclaw.videoplayer.net.CachePolicyPayload}
+     * can only cancel <em>all</em> in-flight downloads at once; a targeted purge needs to stop
+     * exactly one. Each submitted download captures a unique generation here at submit time;
+     * {@link #purge(String)} removes the URL's entry, which makes the running download's
+     * {@link #cancelled(String, long, long)} checks (read loop + every publish point) fail and
+     * self-clean its {@code .part}/promoted file instead of re-publishing post-purge.
+     */
+    private static final Map<String, Long> DOWNLOAD_GEN = new ConcurrentHashMap<>();
+    /** Monotonic source for per-download generations stored in {@link #DOWNLOAD_GEN}. */
+    private static final AtomicLong GEN_SEQ = new AtomicLong(0);
+
+    /**
+     * Single-thread executor that serializes all downloads. Cap enforcement (the total
+     * cache size check) needs an authoritative view of the cache directory at the moment a
+     * download starts, so we run one download at a time — that way the directory scan in
+     * {@link #cacheDirSize} reflects every finished download up to this point. Parallel
+     * downloads were racing the cap by each reading the directory before any of them had
+     * renamed their .part to final.
+     */
+    private static final ExecutorService DOWNLOAD_POOL = Executors.newSingleThreadExecutor(r -> {
+        Thread t = new Thread(r, "video_player-preload");
+        t.setDaemon(true);
+        return t;
+    });
+
+    /**
+     * Hard ceiling on a single preload, in bytes. Default 2 GB sized to allow a single 4K
+     * short clip; overridden per-session by {@link com.ejclaw.videoplayer.net.CachePolicyPayload}
      * on join, which carries the server's {@code max_preload_mb} config value.
      */
-    private static volatile long MAX_BYTES = 750L * 1024 * 1024;
+    private static volatile long MAX_BYTES = 2048L * 1024 * 1024;
+
+    /**
+     * Hard ceiling on the total cache directory size, in bytes. Default 750 MB sized to fit
+     * ~50 short FHD clips; overridden per-session by {@link com.ejclaw.videoplayer.net.CachePolicyPayload}
+     * on join, which carries the server's {@code max_cache_mb} config value. Enforced
+     * cooperatively at the start of each download — running cache + new download must stay
+     * within this cap.
+     */
+    private static volatile long MAX_CACHE_BYTES = 750L * 1024 * 1024;
 
     /** Server-driven override of the per-video cap. */
     public static void setMaxBytes(long bytes) {
         if (bytes < 16L * 1024 * 1024)   bytes = 16L * 1024 * 1024;
         if (bytes > 16L * 1024 * 1024 * 1024) bytes = 16L * 1024 * 1024 * 1024;
         MAX_BYTES = bytes;
-        VideoPlayerMod.LOG.info("[{}] preload cap set to {} MB",
+        VideoPlayerMod.LOG.info("[{}] per-video preload cap set to {} MB",
+            VideoPlayerMod.MOD_ID, bytes / (1024 * 1024));
+    }
+
+    /** Server-driven override of the total-cache cap. */
+    public static void setMaxCacheBytes(long bytes) {
+        if (bytes < 16L * 1024 * 1024)   bytes = 16L * 1024 * 1024;
+        if (bytes > 64L * 1024 * 1024 * 1024) bytes = 64L * 1024 * 1024 * 1024;
+        MAX_CACHE_BYTES = bytes;
+        VideoPlayerMod.LOG.info("[{}] total-cache cap set to {} MB",
             VideoPlayerMod.MOD_ID, bytes / (1024 * 1024));
     }
 
     /** Server-driven delete of a cached URL. Removes from READY and from disk. */
     public static void purge(String url) {
         if (url == null || url.isEmpty()) return;
+        // Cancel any in-flight download of this exact URL first. Dropping its generation
+        // makes the download thread's cancelled() checks fail, so it deletes its own .part
+        // (or rolls back a just-promoted file) instead of finishing and re-publishing after
+        // we've purged. Without this, a slow/large download evicted mid-flight would silently
+        // reappear on disk + in READY once it completed.
+        DOWNLOAD_GEN.remove(url);
         Path p = READY.remove(url);
         if (p == null) {
             // Not in this session's index, but the file may still be on disk from a prior run.
@@ -77,7 +136,6 @@ public final class VideoCache {
                 boolean gone = Files.deleteIfExists(p);
                 VideoPlayerMod.LOG.info("[{}] purge: {} -> deleted={} ({})",
                     VideoPlayerMod.MOD_ID, url, gone, p.getFileName());
-                if (gone) notifyChat("[videocache] 캐시 삭제: " + url, ChatFormatting.YELLOW);
             } catch (Throwable t) {
                 VideoPlayerMod.LOG.warn("[{}] purge failed for {}: {}",
                     VideoPlayerMod.MOD_ID, url, t.toString());
@@ -85,24 +143,90 @@ public final class VideoCache {
         }
     }
 
+    /**
+     * Wipe the entire cache directory and drop both indexes. Sent in response to
+     * {@code /videoCache clear}.
+     *
+     * <p>Three phases that need to stay in this order:
+     * <ol>
+     *   <li>Bump the epoch first — that flips the cancellation flag for any in-flight
+     *       download. The download thread checks the epoch in the read loop and at the
+     *       move step, so after this point it will refuse to publish a new entry and
+     *       will delete its own {@code .part}.</li>
+     *   <li>Clear the in-memory indexes. (READY clears whatever was already finalized
+     *       pre-clear; IN_FLIGHT is wiped so a subsequent same-URL preload re-enters
+     *       the queue instead of getting deduped by stale state.)</li>
+     *   <li>Best-effort delete every regular file in the cache directory. We do this
+     *       last so that if the in-flight download was momentarily holding a {@code .part}
+     *       open, the listing here also catches its post-close residue (though normally
+     *       phase 1 → the download deletes its own part).</li>
+     * </ol>
+     *
+     * <p>Best-effort per-file deletion; logs failures but doesn't abort on the first one.
+     * On Windows the open {@code .part} may not be deletable here — phase 1's cancellation
+     * + the download's own cleanup-on-bail handles that case.
+     */
+    public static void clearAll() {
+        // Phase 1: signal cancellation to any in-flight download BEFORE wiping disk.
+        CACHE_EPOCH.incrementAndGet();
+
+        // Phase 2: drop indexes.
+        READY.clear();
+        IN_FLIGHT.clear();
+        DOWNLOAD_GEN.clear();
+
+        // Phase 3: delete files on disk.
+        int deleted = 0;
+        int failed  = 0;
+        try {
+            Path dir = cacheDir();
+            if (dir != null && Files.isDirectory(dir)) {
+                try (var stream = Files.newDirectoryStream(dir)) {
+                    for (Path p : stream) {
+                        try {
+                            if (Files.isRegularFile(p) && Files.deleteIfExists(p)) deleted++;
+                        } catch (Throwable t) {
+                            failed++;
+                            VideoPlayerMod.LOG.warn("[{}] clearAll: could not delete {}: {}",
+                                VideoPlayerMod.MOD_ID, p.getFileName(), t.toString());
+                        }
+                    }
+                }
+            }
+        } catch (Throwable t) {
+            VideoPlayerMod.LOG.warn("[{}] clearAll failed: {}",
+                VideoPlayerMod.MOD_ID, t.toString());
+        }
+        VideoPlayerMod.LOG.info("[{}] clearAll: deleted={} failed={}",
+            VideoPlayerMod.MOD_ID, deleted, failed);
+    }
+
     /** Kick off a background download. No-op if already cached or in flight. */
     public static void preload(String url) {
         if (url == null || url.isEmpty()) return;
         if (!(url.startsWith("http://") || url.startsWith("https://"))) return;
-        if (READY.containsKey(url)) {
+        // Use lookup() (which also verifies the file exists on disk) instead of
+        // READY.containsKey — defends against READY containing a stale entry whose
+        // backing file was removed by clearAll() / a user-side file delete. Without this,
+        // a stale key would silently block a re-preload.
+        if (lookup(url) != null) {
             VideoPlayerMod.LOG.info("[{}] preload: already cached {}", VideoPlayerMod.MOD_ID, url);
-            notifyChat("[videopreload] 이미 캐시됨: " + url, ChatFormatting.GRAY);
             return;
         }
         if (!IN_FLIGHT.add(url)) {
             VideoPlayerMod.LOG.info("[{}] preload: already downloading {}", VideoPlayerMod.MOD_ID, url);
-            notifyChat("[videopreload] 이미 다운로드 중: " + url, ChatFormatting.GRAY);
             return;
         }
-        notifyChat("[videopreload] 다운로드 시작: " + url, ChatFormatting.YELLOW);
+        VideoPlayerMod.LOG.info("[{}] preload: queued {}", VideoPlayerMod.MOD_ID, url);
-        Thread t = new Thread(() -> download(url), "video_player-preload");
+        // Capture the current epoch at submit time. The download thread checks against
-        t.setDaemon(true);
+        // CACHE_EPOCH later — any mismatch means clearAll() ran in between and this
-        t.start();
+        // download must abort without publishing.
+        long epoch = CACHE_EPOCH.get();
+        // Register a unique generation for this download so a targeted purge() can cancel
+        // exactly this URL (see DOWNLOAD_GEN / cancelled()).
+        long gen = GEN_SEQ.incrementAndGet();
+        DOWNLOAD_GEN.put(url, gen);
+        DOWNLOAD_POOL.submit(() -> download(url, epoch, gen));
     }
 
     /** Return the local cached file path for this URL, or {@code null} if not yet ready. */
@@ -117,6 +241,42 @@ public final class VideoCache {
     public static void clearIndex() {
         READY.clear();
         IN_FLIGHT.clear();
+        DOWNLOAD_GEN.clear();
+    }
+
+    /**
+     * Wipe the cache directory at game shutdown so the user doesn't accumulate disk usage
+     * across sessions. Distinct from {@link #clearAll()}: at shutdown there are no concurrent
+     * downloads to race and no player to chat-notify, so we skip the chat ping but still bump
+     * the epoch (defensive — any straggler write inside the in-flight {@code .part} stream
+     * will detect the bump and self-clean) and drop indexes.
+     */
+    public static void wipeOnShutdown() {
+        CACHE_EPOCH.incrementAndGet();
+        READY.clear();
+        IN_FLIGHT.clear();
+        DOWNLOAD_GEN.clear();
+        int deleted = 0;
+        int failed  = 0;
+        try {
+            Path dir = cacheDir();
+            if (dir != null && Files.isDirectory(dir)) {
+                try (var stream = Files.newDirectoryStream(dir)) {
+                    for (Path p : stream) {
+                        try {
+                            if (Files.isRegularFile(p) && Files.deleteIfExists(p)) deleted++;
+                        } catch (Throwable t) {
+                            failed++;
+                        }
+                    }
+                }
+            }
+        } catch (Throwable t) {
+            VideoPlayerMod.LOG.warn("[{}] wipeOnShutdown failed: {}",
+                VideoPlayerMod.MOD_ID, t.toString());
+        }
+        VideoPlayerMod.LOG.info("[{}] wipeOnShutdown: deleted={} failed={}",
+            VideoPlayerMod.MOD_ID, deleted, failed);
     }
 
     /** Caller-supplied: current set of URLs that are fully cached, for diagnostics. */
@@ -126,28 +286,98 @@ public final class VideoCache {
 
     // -- internals -----------------------------------------------------------------------
 
-    private static void download(String url) {
+    /**
+     * Publish {@code path} into {@link #READY} for {@code url}, but only if the cache
+     * epoch hasn't moved since {@code startEpoch} was captured. Wraps the
+     * pre-check / put / post-check / rollback dance so every publish site uses the
+     * same race-free pattern instead of re-implementing it.
+     *
+     * <p>Race coverage: if {@link #clearAll()} runs at any point between the
+     * pre-check and the post-check, the post-check sees the epoch bump and we
+     * roll back — {@link Map#remove(Object, Object)} is a compareAndRemove so we
+     * don't clobber a legitimate concurrent put under the same key, and we delete
+     * the on-disk file because clearAll's directory scan may have missed it (the
+     * file may not have existed yet when clearAll ran).
+     *
+     * @return {@code true} if the entry is now published; {@code false} if the
+     *         caller's work was cancelled and {@code path} has been cleaned up.
+     */
+    private static boolean publishIfNotCancelled(String url, Path path, long startEpoch, long startGen) {
+        // If a wipe (clearAll) or a targeted purge ran between download's pre-move check and
+        // Files.move, its directory scan won't have seen this just-promoted file. We must
+        // delete it here, not just bail — otherwise the freshly-moved final file leaks.
+        if (cancelled(url, startEpoch, startGen)) {
+            try { Files.deleteIfExists(path); } catch (Throwable ignored) {}
+            return false;
+        }
+        READY.put(url, path);
+        if (cancelled(url, startEpoch, startGen)) {
+            READY.remove(url, path);
+            try { Files.deleteIfExists(path); } catch (Throwable ignored) {}
+            return false;
+        }
+        return true;
+    }
+
+    /**
+     * True if the in-flight download for {@code url} should abort and self-clean. Two channels:
+     * a global wipe ({@link #clearAll()}/{@link #wipeOnShutdown()} bumped {@link #CACHE_EPOCH}),
+     * or a targeted {@link #purge(String)} that removed/replaced this URL's generation in
+     * {@link #DOWNLOAD_GEN}.
+     */
+    private static boolean cancelled(String url, long startEpoch, long startGen) {
+        if (CACHE_EPOCH.get() != startEpoch) return true;
+        Long cur = DOWNLOAD_GEN.get(url);
+        return cur == null || cur.longValue() != startGen;
+    }
+
+    private static void download(String url, long startEpoch, long startGen) {
         Path cacheDir = cacheDir();
+        Path partPath = null;
         try {
             if (cacheDir == null) {
                 VideoPlayerMod.LOG.warn("[{}] preload: no game dir, skipping {}",
                     VideoPlayerMod.MOD_ID, url);
                 return;
             }
+            // Pre-flight cancellation check — if clearAll already ran between submit and now,
+            // skip the whole thing. Avoids creating directories / .part files post-clear.
+            if (cancelled(url, startEpoch, startGen)) {
+                VideoPlayerMod.LOG.info("[{}] preload: cancelled before start (clearAll/purge ran) — {}",
+                    VideoPlayerMod.MOD_ID, url);
+                return;
+            }
             Files.createDirectories(cacheDir);
 
             String hash = sha256(url);
             String ext  = extensionFromUrl(url);
             Path finalPath = cacheDir.resolve(hash + ext);
-            Path partPath  = cacheDir.resolve(hash + ext + ".part");
+            partPath  = cacheDir.resolve(hash + ext + ".part");
 
             // Resume-friendly: if the file's already on disk from an earlier session, just
             // index it without re-downloading.
             if (Files.exists(finalPath) && Files.size(finalPath) > 0) {
-                READY.put(url, finalPath);
+                if (!publishIfNotCancelled(url, finalPath, startEpoch, startGen)) {
+                    VideoPlayerMod.LOG.info("[{}] preload: reindex cancelled (clearAll/purge ran) — {}",
+                        VideoPlayerMod.MOD_ID, url);
+                    return;
+                }
                 VideoPlayerMod.LOG.info("[{}] preload: indexed existing cache {} -> {}",
                     VideoPlayerMod.MOD_ID, url, finalPath.getFileName());
-                notifyChat("[videopreload] 기존 캐시 사용: " + url, ChatFormatting.GREEN);
+                return;
+            }
+
+            // Total-cache check: refuse to start if the cache directory is already at the cap.
+            // We re-check during the read loop too, since other downloads may be in flight in
+            // parallel. {@code existingCacheBytes} excludes our own .part (which we just wrote 0
+            // bytes to / haven't created yet).
+            long existingCacheBytes = cacheDirSize(cacheDir, partPath);
+            if (existingCacheBytes >= MAX_CACHE_BYTES) {
+                long capMb = MAX_CACHE_BYTES / (1024 * 1024);
+                long usedMb = existingCacheBytes / (1024 * 1024);
+                VideoPlayerMod.LOG.warn(
+                    "[{}] preload: total-cache cap reached ({}/{} MB); aborting {}",
+                    VideoPlayerMod.MOD_ID, usedMb, capMb, url);
                 return;
             }
 
@@ -161,56 +391,115 @@ public final class VideoCache {
                 if (code >= 400) {
                     VideoPlayerMod.LOG.warn("[{}] preload: HTTP {} for {}",
                         VideoPlayerMod.MOD_ID, code, url);
-                    notifyChat("[videopreload] 실패 (HTTP " + code + "): " + url, ChatFormatting.RED);
                     return;
                 }
             }
 
             long total = 0;
+            boolean cancelled = false;
             try (InputStream in = raw.getInputStream();
                  OutputStream out = Files.newOutputStream(partPath)) {
                 byte[] buf = new byte[64 * 1024];
                 int n;
                 while ((n = in.read(buf)) >= 0) {
+                    // Cancellation check inside the loop. Break (not return) so the try-with
+                    // closes the output stream first — on Windows, deleting an open .part can
+                    // fail with AccessDeniedException, so we always close before deleting.
+                    if (cancelled(url, startEpoch, startGen)) {
+                        cancelled = true;
+                        break;
+                    }
                     total += n;
                     if (total > MAX_BYTES) {
                         long capMb = MAX_BYTES / (1024 * 1024);
                         VideoPlayerMod.LOG.warn(
-                            "[{}] preload: {} exceeded {} MB cap; aborting",
+                            "[{}] preload: {} exceeded per-video {} MB cap; aborting",
                             VideoPlayerMod.MOD_ID, url, capMb);
-                        try { Files.deleteIfExists(partPath); } catch (Throwable ignored) {}
+                        // Same close-before-delete dance for Windows.
-                        notifyChat("[videopreload] 실패 (" + capMb + "MB 초과): " + url, ChatFormatting.RED);
+                        cancelled = true;
-                        return;
+                        break;
+                    }
+                    if (existingCacheBytes + total > MAX_CACHE_BYTES) {
+                        long capMb = MAX_CACHE_BYTES / (1024 * 1024);
+                        long usedMb = (existingCacheBytes + total) / (1024 * 1024);
+                        VideoPlayerMod.LOG.warn(
+                            "[{}] preload: total-cache cap exceeded ({}>{} MB); aborting {}",
+                            VideoPlayerMod.MOD_ID, usedMb, capMb, url);
+                        cancelled = true;
+                        break;
                     }
                     out.write(buf, 0, n);
                 }
             }
+            // Now the .part file is closed — safe to delete on Windows.
+            if (cancelled) {
+                try { Files.deleteIfExists(partPath); } catch (Throwable ignored) {}
+                return;
+            }
+
+            // Pre-move cancellation check. If clearAll ran during the read loop, abort
+            // before promoting .part to final — saves a wasted move + delete.
+            if (cancelled(url, startEpoch, startGen)) {
+                VideoPlayerMod.LOG.info("[{}] preload: cancelled before move (clearAll/purge ran) — {}",
+                    VideoPlayerMod.MOD_ID, url);
+                try { Files.deleteIfExists(partPath); } catch (Throwable ignored) {}
+                return;
+            }
 
             Files.move(partPath, finalPath, StandardCopyOption.REPLACE_EXISTING,
                 StandardCopyOption.ATOMIC_MOVE);
-            READY.put(url, finalPath);
+
+            // Race-safe publish: this covers the window between Files.move and READY.put
+            // (clearAll deletes the freshly-moved file then we resurrect it in READY) AND
+            // the window between READY.put and the "완료" notification (clearAll wipes
+            // READY then we re-publish + emit stale completion chat). publishIfNotCancelled
+            // rolls back both READY and the on-disk file if the epoch moved at any time.
+            if (!publishIfNotCancelled(url, finalPath, startEpoch, startGen)) {
+                VideoPlayerMod.LOG.info("[{}] preload: cancelled at publish (clearAll/purge ran) — {}",
+                    VideoPlayerMod.MOD_ID, url);
+                return;
+            }
             VideoPlayerMod.LOG.info("[{}] preload: cached {} ({} bytes) -> {}",
                 VideoPlayerMod.MOD_ID, url, total, finalPath.getFileName());
-            long mb = Math.max(1, total / (1024 * 1024));
-            notifyChat("[videopreload] 완료 (" + mb + " MB): " + url, ChatFormatting.GREEN);
         } catch (Throwable t) {
             VideoPlayerMod.LOG.warn("[{}] preload failed for {}: {}",
                 VideoPlayerMod.MOD_ID, url, t.toString());
-            notifyChat("[videopreload] 실패 (" + t.getClass().getSimpleName() + "): " + url,
+            // Best-effort cleanup of any leftover .part on the error path.
-                ChatFormatting.RED);
+            if (partPath != null) {
+                try { Files.deleteIfExists(partPath); } catch (Throwable ignored) {}
+            }
         } finally {
             IN_FLIGHT.remove(url);
+            // Only clear our own generation — a re-preload after a purge may have installed a
+            // newer gen for this URL that must survive.
+            DOWNLOAD_GEN.remove(url, startGen);
         }
     }
 
-    /** Post a status line to the local player's chat. No-op if there's no client/player yet. */
+    /**
-    private static void notifyChat(String text, ChatFormatting color) {
+     * Sum of regular-file sizes under {@code dir}, skipping {@code excludePart} (the .part file
-        Minecraft mc = Minecraft.getInstance();
+     * for the in-flight download — we account for that via the running {@code total} counter).
-        if (mc == null) return;
+     * Best-effort: errors collapse to 0 so a transient FS hiccup doesn't strand a download.
-        mc.execute(() -> {
+     */
-            if (mc.player == null) return;
+    private static long cacheDirSize(Path dir, Path excludePart) {
-            mc.player.sendSystemMessage(Component.literal(text).withStyle(color));
+        if (dir == null) return 0L;
-        });
+        try {
+            if (!Files.isDirectory(dir)) return 0L;
+            final long[] sum = { 0L };
+            try (var stream = Files.newDirectoryStream(dir)) {
+                for (Path p : stream) {
+                    if (excludePart != null && p.equals(excludePart)) continue;
+                    try {
+                        if (Files.isRegularFile(p)) sum[0] += Files.size(p);
+                    } catch (Throwable ignored) {}
+                }
+            }
+            return sum[0];
+        } catch (Throwable t) {
+            VideoPlayerMod.LOG.warn("[{}] cacheDirSize failed: {}",
+                VideoPlayerMod.MOD_ID, t.toString());
+            return 0L;
+        }
     }
 
     private static Path cacheDir() {

src/main/java/com/ejclaw/videoplayer/client/render/VideoAnchorRenderer.java

@@ -31,8 +31,19 @@ import org.joml.Matrix4f;
 @Environment(EnvType.CLIENT)
 public class VideoAnchorRenderer implements BlockEntityRenderer<VideoAnchorBlockEntity, VideoAnchorRenderer.State> {
 
-    /** Tiny outward offset so the quad doesn't z-fight with the wall. */
+    /**
-    private static final float SURFACE_EPSILON = 0.001F;
+     * Outward offset so the quad doesn't z-fight with the wall it sits on.
+     *
+     * <p>Depth-buffer precision drops with the square of view distance: with near=0.05 and
+     * 24-bit depth, the smallest resolvable step at 30 blocks is ~1mm, and ~12mm at 100
+     * blocks. The old 0.001 (1mm) offset was right at the precision boundary at ~30 blocks
+     * — which is exactly the distance users started seeing the wall texture flicker through
+     * the video panel once {@code render_distance_blocks} was raised past the default.
+     *
+     * <p>2cm gives ~20× margin at 30 blocks and is still visually unnoticeable up close
+     * (~3% of a block thickness).
+     */
+    private static final float SURFACE_EPSILON = 0.02F;
 
     public VideoAnchorRenderer(BlockEntityRendererProvider.Context ctx) {
         // no-op
@@ -75,7 +86,12 @@ public class VideoAnchorRenderer implements BlockEntityRenderer<VideoAnchorBlock
         pose.translate(-0.5F, -0.5F, -0.5F + SURFACE_EPSILON);
 
         final Matrix4f mat = new Matrix4f(pose.last().pose());
-        RenderType rt = RenderTypes.entityCutout(tex);
+        // entitySolid (not entityCutout): video frames come from swscale → AV_PIX_FMT_RGBA with
+        // alpha hard-set to 255, so there is no alpha-tested cutout. Cutout's alpha-discard step
+        // adds nothing here and makes distant sampling unstable — without mipmaps on a dynamic
+        // texture, neighbouring texels can shimmer above/below the discard threshold at sub-pixel
+        // sampling rates, contributing to the flicker users see once render distance is raised.
+        RenderType rt = RenderTypes.entitySolid(tex);
         collector.submitCustomGeometry(pose, rt, (poseUnused, vc) -> {
             // Single-sided: the back of the anchor is by design pressed against the wall the
             // player clicked, so a back face is pure GPU waste. Halves the fragment shader work

src/main/java/com/ejclaw/videoplayer/command/CommandPermissions.java

@@ -0,0 +1,45 @@
+package com.ejclaw.videoplayer.command;
+
+import net.minecraft.commands.CommandSourceStack;
+import net.minecraft.server.permissions.Permissions;
+import net.minecraft.world.entity.player.Player;
+
+/**
+ * Shared {@code .requires(...)} predicate for all {@code /video*} commands.
+ *
+ * <p>Semantics:
+ * <ul>
+ *   <li><b>Player source</b> — must be OP (permission level ≥ 2, via
+ *       {@link Permissions#COMMANDS_GAMEMASTER}). Non-OP players don't even see the command
+ *       in tab-completion.</li>
+ *   <li><b>Non-player source</b> — server console, command block, and datapack
+ *       {@code /function} are always allowed regardless of any permission level
+ *       or gamerule. This means admins don't need to bump {@code functionPermissionLevel}
+ *       just to drive {@code /videoPlace} etc. from a datapack function.</li>
+ * </ul>
+ *
+ * <p>The bypass for non-player sources is safe because reaching one of those execution
+ * contexts already requires server-operator trust:
+ * <ul>
+ *   <li>Console — physical/admin access to the server.</li>
+ *   <li>Command block — placing one requires OP + {@code /gamerule sendCommandFeedback}
+ *       privileges, and {@code /execute as} preserves the underlying source's permissions
+ *       (so a non-OP player can't smuggle commands through one).</li>
+ *   <li>Datapack function — installed by the server admin.</li>
+ * </ul>
+ */
+public final class CommandPermissions {
+    private CommandPermissions() {}
+
+    /**
+     * Returns {@code true} when the source is allowed to run a {@code /video*} command.
+     *
+     * <p>Player → OP only. Anything else → always allowed.
+     */
+    public static boolean opOrServer(CommandSourceStack s) {
+        if (s.getEntity() instanceof Player) {
+            return s.permissions().hasPermission(Permissions.COMMANDS_GAMEMASTER);
+        }
+        return true;
+    }
+}

src/main/java/com/ejclaw/videoplayer/command/VideoCacheCommand.java

@@ -1,6 +1,7 @@
 package com.ejclaw.videoplayer.command;
 
 import com.ejclaw.videoplayer.VideoPlayerConfig;
+import com.ejclaw.videoplayer.net.ClearCachePayload;
 import com.ejclaw.videoplayer.net.DeleteCachePayload;
 import com.ejclaw.videoplayer.net.PreloadPayload;
 import com.mojang.brigadier.CommandDispatcher;
@@ -19,7 +20,6 @@ import net.minecraft.network.chat.MutableComponent;
 import net.minecraft.network.chat.Style;
 import net.minecraft.server.MinecraftServer;
 import net.minecraft.server.level.ServerPlayer;
-import net.minecraft.server.permissions.Permissions;
 
 import java.net.URI;
 import java.util.Map;
@@ -31,8 +31,9 @@ import java.util.Map;
  * <br>{@code /videocache remove <name>} — drop the entry from server config and tell every client
  * to delete the matching cache file.
  *
- * <p>Replaces the old {@code /videopreload}. Same permission gate
+ * <p>Replaces the old {@code /videopreload}. Permission gate via
- * ({@link Permissions#COMMANDS_GAMEMASTER}) so command blocks can drive it.
+ * {@link CommandPermissions#opOrServer(CommandSourceStack)} so command blocks and datapack
+ * functions can drive it without touching {@code functionPermissionLevel}.
  */
 public final class VideoCacheCommand {
     private VideoCacheCommand() {}
@@ -43,7 +44,7 @@ public final class VideoCacheCommand {
 
     private static LiteralArgumentBuilder<CommandSourceStack> build(String root) {
         return Commands.literal(root)
-            .requires(s -> s.permissions().hasPermission(Permissions.COMMANDS_GAMEMASTER))
+            .requires(CommandPermissions::opOrServer)
             .then(Commands.literal("add")
                 .then(Commands.argument("name", StringArgumentType.word())
                     .then(Commands.argument("url", StringArgumentType.greedyString())
@@ -127,26 +128,26 @@ public final class VideoCacheCommand {
 
     private static int runClear(CommandContext<CommandSourceStack> ctx) {
         CommandSourceStack src = ctx.getSource();
+        // Drop server-side named entries (preload_urls is left alone — it's an admin-edited
+        // list, not something /videoCache manages).
         java.util.List<String> urls = VideoPlayerConfig.clearCacheEntries();
-        if (urls.isEmpty()) {
+
-            src.sendSuccess(() -> Component.literal("[videocache] 저장된 항목이 없습니다")
+        // Always broadcast a full-cache wipe to every client, even if the named index was
-                .withStyle(ChatFormatting.GRAY), false);
+        // empty — leftover files from prior sessions, legacy preload_urls downloads, and
-            return 0;
+        // any in-flight stragglers all get scrubbed in one shot.
-        }
         MinecraftServer server = src.getServer();
+        ClearCachePayload payload = new ClearCachePayload();
         int clients = 0;
         for (ServerPlayer p : PlayerLookup.all(server)) {
-            for (String url : urls) {
+            ServerPlayNetworking.send(p, payload);
-                ServerPlayNetworking.send(p, new DeleteCachePayload(url));
-            }
             clients++;
         }
         final int sentFinal = clients;
         final int countFinal = urls.size();
         src.sendSuccess(() -> Component.literal(
-            "[videocache] 전체 삭제: " + countFinal + "개 항목"
+            "[videocache] 전체 삭제: 등록 항목 " + countFinal + "개 제거"
-                + "  (" + sentFinal + " 클라이언트에 cache_delete 전송)"), false);
+                + " + " + sentFinal + " 클라이언트 디스크 캐시 전체 wipe"), false);
-        return countFinal;
+        return Math.max(countFinal, 1);
     }
 
     private static int runRemove(CommandContext<CommandSourceStack> ctx) throws CommandSyntaxException {

src/main/java/com/ejclaw/videoplayer/command/VideoDeleteCommand.java

@@ -9,7 +9,6 @@ import net.minecraft.commands.arguments.coordinates.BlockPosArgument;
 import net.minecraft.core.BlockPos;
 import net.minecraft.network.chat.Component;
 import net.minecraft.server.level.ServerLevel;
-import net.minecraft.server.permissions.Permissions;
 import net.minecraft.world.level.block.Block;
 import net.minecraft.world.level.block.Blocks;
 
@@ -24,7 +23,7 @@ public final class VideoDeleteCommand {
     private static com.mojang.brigadier.builder.LiteralArgumentBuilder<CommandSourceStack>
     build(String name) {
         return Commands.literal(name)
-            .requires(s -> s.permissions().hasPermission(Permissions.COMMANDS_GAMEMASTER))
+            .requires(CommandPermissions::opOrServer)
             .then(Commands.argument("pos", BlockPosArgument.blockPos())
                 .executes(VideoDeleteCommand::run));
     }
@@ -39,7 +38,7 @@ public final class VideoDeleteCommand {
             return 0;
         }
         level.setBlock(pos, Blocks.AIR.defaultBlockState(), Block.UPDATE_ALL);
-        src.sendSuccess(() -> Component.literal("anchor deleted at " + pos.toShortString()), true);
+        src.sendSuccess(() -> Component.literal("anchor deleted at " + pos.toShortString()), false);
         return 1;
     }
 }

src/main/java/com/ejclaw/videoplayer/command/VideoMuteCommand.java

@@ -14,7 +14,6 @@ import net.minecraft.core.BlockPos;
 import net.minecraft.network.chat.Component;
 import net.minecraft.server.level.ServerLevel;
 import net.minecraft.server.level.ServerPlayer;
-import net.minecraft.server.permissions.Permissions;
 
 /** SPEC §4.5.1 — {@code /videoMute <pos> <on|off>} */
 public final class VideoMuteCommand {
@@ -27,7 +26,7 @@ public final class VideoMuteCommand {
     private static com.mojang.brigadier.builder.LiteralArgumentBuilder<CommandSourceStack>
     build(String name) {
         return Commands.literal(name)
-            .requires(s -> s.permissions().hasPermission(Permissions.COMMANDS_GAMEMASTER))
+            .requires(CommandPermissions::opOrServer)
             .then(Commands.argument("pos", BlockPosArgument.blockPos())
                 .then(Commands.argument("state", StringArgumentType.word())
                     .executes(VideoMuteCommand::run)));
@@ -55,7 +54,7 @@ public final class VideoMuteCommand {
             ServerPlayNetworking.send(p, new SyncAnchorPayload(pos, be.toNbt()));
         }
         final boolean mFinal = muted;
-        src.sendSuccess(() -> Component.literal("anchor " + (mFinal ? "muted" : "unmuted")), true);
+        src.sendSuccess(() -> Component.literal("anchor " + (mFinal ? "muted" : "unmuted")), false);
         return 1;
     }
 }

src/main/java/com/ejclaw/videoplayer/command/VideoPlaceCommand.java

@@ -19,13 +19,32 @@ import net.minecraft.nbt.CompoundTag;
 import net.minecraft.network.chat.Component;
 import net.minecraft.server.level.ServerLevel;
 import net.minecraft.server.level.ServerPlayer;
-import net.minecraft.server.permissions.Permissions;
 import net.minecraft.world.level.block.Block;
 
-/** SPEC §4.5.1 — {@code /videoPlace <pos> <facing> <width> <height> <url>} */
+/**
+ * SPEC §4.5.1 — {@code /videoPlace} has two accepted forms:
+ *
+ * <ul>
+ *   <li><b>Legacy 5-arg</b>: {@code /videoPlace <pos> <facing> <width> <height> <url>}
+ *       — preserved for existing command blocks. Volume defaults to 50% and muted=false.
+ *       The {@code url} here is a single-token string so it doesn't swallow the {@code volume}
+ *       slot of the new form.</li>
+ *   <li><b>New 6-arg</b>: {@code /videoPlace <pos> <facing> <width> <height> <volume> <url>}
+ *       — {@code volume} is 0..100 (percent) or {@code -1} to start muted. The percent form
+ *       mirrors the GUI slider; {@code -1} is a CLI shortcut so admins don't need a follow-up
+ *       {@code /videoMute} step. {@code url} is greedy here, so URLs containing spaces (rare
+ *       but possible after URL-decoding) still work.</li>
+ * </ul>
+ *
+ * <p>Brigadier disambiguates the two by the type of the 5th argument: integer → new form,
+ * non-integer token → legacy form.
+ */
 public final class VideoPlaceCommand {
     private VideoPlaceCommand() {}
 
+    /** Default volume (percent) applied to the legacy 5-arg form. */
+    private static final int DEFAULT_VOLUME_PCT = 50;
+
     public static void register(CommandDispatcher<CommandSourceStack> dispatcher) {
         dispatcher.register(build("videoPlace"));
     }
@@ -33,17 +52,38 @@ public final class VideoPlaceCommand {
     private static com.mojang.brigadier.builder.LiteralArgumentBuilder<CommandSourceStack>
     build(String name) {
         return Commands.literal(name)
-            .requires(s -> s.permissions().hasPermission(Permissions.COMMANDS_GAMEMASTER))
+            .requires(CommandPermissions::opOrServer)
             .then(Commands.argument("pos", BlockPosArgument.blockPos())
                 .then(Commands.argument("facing", StringArgumentType.word())
                     .then(Commands.argument("width", IntegerArgumentType.integer(1, 32))
                         .then(Commands.argument("height", IntegerArgumentType.integer(1, 32))
-                            .then(Commands.argument("url", StringArgumentType.greedyString())
+                            // New form: volume (int) + greedy url
-                                .executes(VideoPlaceCommand::run))))));
+                            .then(Commands.argument("volume", IntegerArgumentType.integer(-1, 100))
+                                .then(Commands.argument("url", StringArgumentType.greedyString())
+                                    .executes(ctx -> runNew(ctx))))
+                            // Legacy form: single-token url, no volume slot. Single-token string
+                            // is intentional so "<int> https://..." cannot be parsed as a legacy
+                            // url that happens to start with a number — Brigadier first tries the
+                            // new branch and only falls through here if "volume" isn't an int.
+                            .then(Commands.argument("url", StringArgumentType.string())
+                                .executes(ctx -> runLegacy(ctx)))))));
     }
 
-    private static int run(com.mojang.brigadier.context.CommandContext<CommandSourceStack> ctx)
+    private static int runNew(com.mojang.brigadier.context.CommandContext<CommandSourceStack> ctx)
             throws CommandSyntaxException {
+        int volumeArg = IntegerArgumentType.getInteger(ctx, "volume");
+        String url = StringArgumentType.getString(ctx, "url");
+        return runWithValues(ctx, volumeArg, url);
+    }
+
+    private static int runLegacy(com.mojang.brigadier.context.CommandContext<CommandSourceStack> ctx)
+            throws CommandSyntaxException {
+        String url = StringArgumentType.getString(ctx, "url");
+        return runWithValues(ctx, DEFAULT_VOLUME_PCT, url);
+    }
+
+    private static int runWithValues(com.mojang.brigadier.context.CommandContext<CommandSourceStack> ctx,
+                                     int volumeArg, String rawUrl) throws CommandSyntaxException {
         CommandSourceStack src = ctx.getSource();
         ServerLevel level = src.getLevel();
         BlockPos pos = BlockPosArgument.getLoadedBlockPos(ctx, "pos");
@@ -54,7 +94,12 @@ public final class VideoPlaceCommand {
         }
         int width  = IntegerArgumentType.getInteger(ctx, "width");
         int height = IntegerArgumentType.getInteger(ctx, "height");
-        String raw = StringArgumentType.getString(ctx, "url").trim();
+        // -1 is the CLI mute shortcut; the BE keeps the underlying volume so an admin can
+        // /videoMute false later without re-typing a level. Anything 0..100 sets %-volume and
+        // clears mute.
+        boolean placeMuted = volumeArg < 0;
+        float placeVolume = placeMuted ? 0.5F : (volumeArg / 100.0F);
+        String raw = rawUrl == null ? "" : rawUrl.trim();
         // Accept either an http(s) URL or a /videoCache add <name> entry: resolveUrlOrName()
         // returns the canonical URL in both cases, or null when a non-URL string didn't match
         // any named entry.
@@ -75,13 +120,15 @@ public final class VideoPlaceCommand {
         be.setWidth(width);
         be.setHeight(height);
         be.setUrl(url);
+        be.setVolume(placeVolume);
+        be.setMuted(placeMuted);
 
         CompoundTag nbt = be.toNbt();
         for (ServerPlayer p : PlayerLookup.tracking(level, pos)) {
             ServerPlayNetworking.send(p, new SyncAnchorPayload(pos, nbt));
         }
         final BlockPos fp = pos;
-        src.sendSuccess(() -> Component.literal("anchor placed at " + fp.toShortString()), true);
+        src.sendSuccess(() -> Component.literal("anchor placed at " + fp.toShortString()), false);
         return 1;
     }
 

src/main/java/com/ejclaw/videoplayer/command/VideoStickCommand.java

@@ -12,7 +12,11 @@ public final class VideoStickCommand {
     private VideoStickCommand() {}
 
     public static void register(CommandDispatcher<CommandSourceStack> dispatcher) {
+        // 플레이어는 OP(level 2+) 만, 콘솔/커맨드블럭/함수(/function) 는 무조건 통과.
+        // 따라서 functionPermissionLevel 같은 gamerule 을 만질 필요가 없다.
+        // 일반 플레이어(level 0) 는 탭 자동완성에도 안 떠야 정상.
         dispatcher.register(Commands.literal("videoStick")
+            .requires(CommandPermissions::opOrServer)
             .executes(ctx -> run(ctx.getSource())));
     }
 

src/main/java/com/ejclaw/videoplayer/net/CachePolicyPayload.java

@@ -9,15 +9,18 @@ import net.minecraft.resources.Identifier;
 
 /**
  * S2C — broadcasts the server-configured client-side policy bundle on join, before any
- * {@link PreloadPayload}. Currently carries: {@code maxBytes} (per-video download cap) and
+ * {@link PreloadPayload}. Carries: {@code maxPerVideoBytes} (per-video download cap),
- * {@code renderDistanceBlocks} (anchor BE view-distance cap).
+ * {@code maxCacheBytes} (total-cache directory cap), and {@code renderDistanceBlocks}
+ * (anchor BE view-distance cap).
  */
-public record CachePolicyPayload(long maxBytes, int renderDistanceBlocks) implements CustomPacketPayload {
+public record CachePolicyPayload(long maxPerVideoBytes, long maxCacheBytes, int renderDistanceBlocks)
+        implements CustomPacketPayload {
     public static final CustomPacketPayload.Type<CachePolicyPayload> TYPE =
         new CustomPacketPayload.Type<>(Identifier.fromNamespaceAndPath(VideoPlayerMod.MOD_ID, "cache_policy"));
 
     public static final StreamCodec<RegistryFriendlyByteBuf, CachePolicyPayload> CODEC = StreamCodec.composite(
-        ByteBufCodecs.VAR_LONG, CachePolicyPayload::maxBytes,
+        ByteBufCodecs.VAR_LONG, CachePolicyPayload::maxPerVideoBytes,
+        ByteBufCodecs.VAR_LONG, CachePolicyPayload::maxCacheBytes,
         ByteBufCodecs.VAR_INT,  CachePolicyPayload::renderDistanceBlocks,
         CachePolicyPayload::new
     );

src/main/java/com/ejclaw/videoplayer/net/ClearCachePayload.java

@@ -0,0 +1,26 @@
+package com.ejclaw.videoplayer.net;
+
+import com.ejclaw.videoplayer.VideoPlayerMod;
+import net.minecraft.network.RegistryFriendlyByteBuf;
+import net.minecraft.network.codec.StreamCodec;
+import net.minecraft.network.protocol.common.custom.CustomPacketPayload;
+import net.minecraft.resources.Identifier;
+
+/**
+ * S2C — tell every client to wipe its entire {@code video_player_cache} directory and reset
+ * the in-memory READY/IN_FLIGHT index. Sent by {@code /videoCache clear}. Carries no payload —
+ * the receiving client just nukes everything under the cache dir regardless of how the file
+ * got there (named entry, legacy preload_url, or leftover from a prior session).
+ */
+public record ClearCachePayload() implements CustomPacketPayload {
+    public static final CustomPacketPayload.Type<ClearCachePayload> TYPE =
+        new CustomPacketPayload.Type<>(Identifier.fromNamespaceAndPath(VideoPlayerMod.MOD_ID, "cache_clear"));
+
+    public static final StreamCodec<RegistryFriendlyByteBuf, ClearCachePayload> CODEC =
+        StreamCodec.unit(new ClearCachePayload());
+
+    @Override
+    public Type<? extends CustomPacketPayload> type() {
+        return TYPE;
+    }
+}

src/main/java/com/ejclaw/videoplayer/net/MqHelloPayload.java

@@ -0,0 +1,35 @@
+package com.ejclaw.videoplayer.net;
+
+import com.ejclaw.videoplayer.VideoPlayerMod;
+import net.minecraft.network.RegistryFriendlyByteBuf;
+import net.minecraft.network.codec.ByteBufCodecs;
+import net.minecraft.network.codec.StreamCodec;
+import net.minecraft.network.protocol.common.custom.CustomPacketPayload;
+import net.minecraft.resources.Identifier;
+
+/**
+ * C2S — client-presence handshake for the {@code music_quiz} datapack
+ * ({@code docs/mc_video_player_mod_integration.md}). Each modded client sends one on JOIN
+ * and one every ~5 s thereafter. The server side flips the player's {@code mq_video_mod}
+ * scoreboard score to {@code 1}, which the datapack reads in its {@code mq:commands/start}
+ * guard.
+ *
+ * <p>Payload body is a single int (protocol version) so future schema bumps don't require
+ * a new packet id. v1 is the only version that exists today.
+ */
+public record MqHelloPayload(int version) implements CustomPacketPayload {
+    public static final int CURRENT_VERSION = 1;
+
+    public static final CustomPacketPayload.Type<MqHelloPayload> TYPE =
+        new CustomPacketPayload.Type<>(Identifier.fromNamespaceAndPath(VideoPlayerMod.MOD_ID, "mq_hello"));
+
+    public static final StreamCodec<RegistryFriendlyByteBuf, MqHelloPayload> CODEC = StreamCodec.composite(
+        ByteBufCodecs.VAR_INT, MqHelloPayload::version,
+        MqHelloPayload::new
+    );
+
+    @Override
+    public Type<? extends CustomPacketPayload> type() {
+        return TYPE;
+    }
+}

src/main/java/com/ejclaw/videoplayer/net/VideoPlayerNetwork.java

@@ -28,9 +28,11 @@ public final class VideoPlayerNetwork {
         PayloadTypeRegistry.clientboundPlay().register(PreloadPayload.TYPE, PreloadPayload.CODEC);
         PayloadTypeRegistry.clientboundPlay().register(CachePolicyPayload.TYPE, CachePolicyPayload.CODEC);
         PayloadTypeRegistry.clientboundPlay().register(DeleteCachePayload.TYPE, DeleteCachePayload.CODEC);
+        PayloadTypeRegistry.clientboundPlay().register(ClearCachePayload.TYPE, ClearCachePayload.CODEC);
         // C2S
         PayloadTypeRegistry.serverboundPlay().register(SaveConfigPayload.TYPE, SaveConfigPayload.CODEC);
         PayloadTypeRegistry.serverboundPlay().register(DeleteAnchorPayload.TYPE, DeleteAnchorPayload.CODEC);
+        PayloadTypeRegistry.serverboundPlay().register(MqHelloPayload.TYPE, MqHelloPayload.CODEC);
     }
 
     public static void registerServerReceivers() {

src/main/java/com/ejclaw/videoplayer/server/MusicQuizPresence.java

@@ -0,0 +1,74 @@
+package com.ejclaw.videoplayer.server;
+
+import com.ejclaw.videoplayer.VideoPlayerMod;
+import com.ejclaw.videoplayer.net.MqHelloPayload;
+import net.fabricmc.fabric.api.event.lifecycle.v1.ServerTickEvents;
+import net.fabricmc.fabric.api.networking.v1.ServerPlayNetworking;
+import net.minecraft.server.MinecraftServer;
+import net.minecraft.server.level.ServerPlayer;
+import net.minecraft.world.scores.Objective;
+import net.minecraft.world.scores.ScoreHolder;
+import net.minecraft.world.scores.Scoreboard;
+
+/**
+ * Implements the server side of the {@code music_quiz} datapack handshake described in
+ * {@code docs/mc_video_player_mod_integration.md}.
+ *
+ * <p>Two scoreboard writes against objective {@code mq_video_mod} (dummy):
+ * <ul>
+ *   <li>Every server tick — {@code #server mq_video_mod = 1}. Proves the mod jar is on the
+ *       server side. The datapack's {@code mq:commands/start} guard checks this first.</li>
+ *   <li>Every received {@link MqHelloPayload} — {@code <player> mq_video_mod = 1}. Proves
+ *       the sending player's client has the mod installed. Per-player flag is needed
+ *       because rendering is client-side; the server can't tell from join state alone.</li>
+ * </ul>
+ *
+ * <p>The objective itself ({@code scoreboard objectives add mq_video_mod dummy}) is
+ * created by the datapack's {@code mq:load} function. If it isn't present yet (datapack
+ * not applied, or load hasn't run), the writes are silently skipped — when the datapack
+ * appears later, the next tick / next payload arrival populates it.
+ */
+public final class MusicQuizPresence {
+    private MusicQuizPresence() {}
+
+    /** Scoreboard objective name expected by the {@code music_quiz} datapack. */
+    private static final String OBJECTIVE = "mq_video_mod";
+    /** Fake holder used to mark "the server has the mod" (datapack reads {@code #server}). */
+    private static final String SERVER_HOLDER = "#server";
+
+    /** Call from {@code VideoPlayerMod.onInitialize} after payload types are registered. */
+    public static void register() {
+        // (a) per-tick server presence
+        ServerTickEvents.END_SERVER_TICK.register(MusicQuizPresence::onServerTick);
+
+        // (b) per-player client presence — flipped on every received Hello
+        ServerPlayNetworking.registerGlobalReceiver(MqHelloPayload.TYPE, (payload, context) -> {
+            ServerPlayer player = context.player();
+            MinecraftServer server = context.server();
+            // hop back onto the server thread before touching the scoreboard
+            server.execute(() -> markPlayerPresent(server, player));
+        });
+    }
+
+    private static void onServerTick(MinecraftServer server) {
+        Scoreboard sb = server.getScoreboard();
+        Objective obj = sb.getObjective(OBJECTIVE);
+        // Datapack not loaded yet — silently skip. The score holder doesn't exist until
+        // the objective does, and trying to write blind would just blow up.
+        if (obj == null) return;
+        sb.getOrCreatePlayerScore(ScoreHolder.forNameOnly(SERVER_HOLDER), obj).set(1);
+    }
+
+    private static void markPlayerPresent(MinecraftServer server, ServerPlayer player) {
+        Scoreboard sb = server.getScoreboard();
+        Objective obj = sb.getObjective(OBJECTIVE);
+        if (obj == null) {
+            VideoPlayerMod.LOG.debug("[{}] mq hello from {} but objective '{}' not present",
+                VideoPlayerMod.MOD_ID, player.getName().getString(), OBJECTIVE);
+            return;
+        }
+        // ServerPlayer itself implements ScoreHolder, so this matches selector @s on the
+        // datapack side without name-formatting quirks (uuid vs profile name).
+        sb.getOrCreatePlayerScore(player, obj).set(1);
+    }
+}