v0.4.7: smoother playback via memcpy upload + render-rate pump

- Replace per-pixel RGBA->ABGR loop in Entry.upload() with a single MemoryUtil.memCopy() into NativeImage's native buffer. The two layouts are identical when viewed as little-endian bytes, so no swap is needed. Cuts 1080p upload time from a ~2M-iter Java loop to one native memcpy. - Move the frame-pump tick from 20Hz client tick (END_CLIENT_TICK) to per-render-frame (LevelRenderEvents.START_MAIN). At 60+fps display vs 24fps source, this removes the worst stutter window where a decoded frame waited up to 50ms for the next tick. Distance-gain math stays on 20Hz where it's plenty. - Bump version 0.4.6 -> 0.4.7 in gradle.properties and README.
v0.4.6: server config for auto-preload on join
2026-05-15 22:06:15 +09:00 · 2026-05-15 21:58:26 +09:00 · 2026-05-15 21:53:21 +09:00 · 2026-05-15 21:42:11 +09:00 · 2026-05-15 21:22:02 +09:00 · 2026-05-15 21:04:49 +09:00
40 changed files with 2537 additions and 112 deletions
--- a/.gitea/workflows/build.yml
+++ b/.gitea/workflows/build.yml
@@ -0,0 +1,23 @@
+name: build
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 25
+      - name: Build (MC 26.1.2)
+        run: ./gradlew --no-daemon build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: video_player-mc26.1.2
+          path: build/libs/*.jar
--- a/README.md
+++ b/README.md
@@ -1,29 +1,248 @@
 # video_player (영상재생모드)

-마인크래프트(Fabric, MC 1.21.6+) 안에서 임의의 mp4 URL을 블록 표면에 재생하는 모드.
+마인크래프트 안에서 임의의 동영상 URL을 벽·바닥·천장에 평면으로 재생하는 Fabric 모드.

 - 모드 ID: `video_player`
- 한글명: 영상재생모드
- 로더: Fabric (싱글플레이어 / 전용 서버 양쪽 지원)
- 명세: 별도 SPEC 문서 참조
+- 현재 버전: **0.4.7**
+- 마인크래프트 버전: **26.1.2**
+- 필요 Java: **25** (마인크래프트 26.x 가 요구함)

-## 빌드
+---

-```sh
-JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64 ./gradlew build
+## 처음 사용하는 분을 위한 설치 가이드
+
+이 모드는 마인크래프트 **공식 런처**에 **Fabric**을 설치해서 쓰는 것을 기준으로 합니다. 차근차근 따라오시면 됩니다.
+
+### STEP 1. 마인크래프트 공식 런처를 켜고 최소 1회 26.1.2 바닐라로 접속
+
+런처 메뉴에서 마인크래프트 버전을 **26.1.2** 로 한 번 실행해 두면, 게임 폴더(`.minecraft`)와 `versions/26.1.2/` 가 자동으로 만들어집니다. 월드를 만들 필요는 없고 메인 화면까지만 들어가면 됩니다.
+
+### STEP 2. Fabric 설치하기
+
+Fabric은 마인크래프트에 모드 기능을 추가해 주는 로더입니다.
+
+1. https://fabricmc.net/use/installer/ 에 접속해서 "Download for Windows" (또는 macOS / Linux)를 누릅니다. `fabric-installer-1.x.x.exe` (또는 `.jar`) 파일이 다운로드 됩니다.
+2. 받은 파일을 **더블 클릭** 으로 실행합니다.
+3. 창이 뜨면:
+   - **클라이언트** 탭이 선택되어 있는지 확인
+   - 마인크래프트 버전: **26.1.2**
+   - 로더 버전: **0.19.2** (또는 그보다 높은 숫자)
+   - 설치 위치는 그대로 두세요
+4. **설치** 버튼을 누르고 완료 메시지가 뜨면 닫습니다.
+5. 다시 공식 마인크래프트 런처를 열면 좌측 하단 프로필 선택 칸에 **`fabric-loader-0.19.2-26.1.2`** (이름 비슷한 항목) 이 새로 생겨 있습니다. 이 프로필을 선택합니다.
+
+### STEP 3. 모드 폴더 열기
+
+선택한 fabric 프로필 옆에 톱니바퀴 ⚙ 모양 아이콘이나 "편집" 버튼이 있습니다. (없으면 그냥 한 번 플레이를 눌러서 게임을 띄웠다가 닫으면 폴더가 만들어집니다.)
+
+`.minecraft/mods` 폴더가 모드를 넣는 곳입니다. 운영체제별 경로:
+
+- **Windows**: 키보드에서 `윈도우키+R` → `%appdata%\.minecraft\mods` 입력 → 엔터
+- **macOS**: Finder → `Go` 메뉴 → `Go to Folder` → `~/Library/Application Support/minecraft/mods`
+- **Linux**: `~/.minecraft/mods`
+
+폴더가 없으면 `mods` 라는 이름으로 직접 만드세요.
+
+### STEP 4. 모드 jar 파일 두 개를 mods 폴더에 넣기
+
+1. **Fabric API** (Fabric 모드들이 공통으로 쓰는 라이브러리. 거의 모든 Fabric 모드에 필요)
+   - **반드시 26.1.2 용으로 받아야 합니다.** 파일명 끝에 `+26.1.2.jar` 가 붙어있는지 꼭 확인하세요. `+1.21.11.jar` 같은 다른 버전을 받으면 게임이 "Incompatible mods found / requires Minecraft 1.21.x" 에러로 안 켜집니다.
+   - 직접 다운로드 (2026-05-14 빌드, MC 26.1.2 전용):
+     https://cdn.modrinth.com/data/P7dR8mSH/versions/Sy2Bq7Xc/fabric-api-0.149.0%2B26.1.2.jar
+   - 더 최신 빌드를 찾을 땐: https://modrinth.com/mod/fabric-api/versions → 페이지에서 게임 버전 필터 `26.1.2` 를 직접 선택. (URL 파라미터 필터가 듣지 않는 경우가 있어서 페이지 안에서 한 번 더 확인하는 게 안전합니다.)
+   - 받은 `fabric-api-0.149.0+26.1.2.jar` 를 `mods` 폴더에 넣습니다.
+2. **video_player** (이 모드)
+   - 다운로드: https://git.tkrmagid.kr/tkrmagid/mc_video_player_mod/releases
+   - `video_player-0.4.7.jar` 를 다운로드해서 같은 `mods` 폴더에 넣습니다.
+
+이전 버전(`video_player-0.4.0.jar`, `0.4.2.jar`, `0.4.3.jar`, `0.3.x.jar` 등)이 mods 폴더에 남아있다면 **반드시 삭제**하세요. 두 개가 같이 있으면 마인크래프트가 충돌로 켜지지 않습니다.
+
+### STEP 5. 영상 재생 라이브러리 (JavaCV) 설치
+
+여기까지만 하면 마인크래프트는 켜지지만, 영상 자리에 검은 판만 보입니다. 진짜 영상을 재생하려면 **JavaCV** 라는 디코더 라이브러리가 필요합니다.
+
+> 솔직한 안내: 마인크래프트 공식 런처는 mods 폴더에 들어있는 일반 라이브러리 jar를 자동으로 읽어 주지 않습니다. 그래서 JavaCV 설치 절차가 조금 번거롭습니다. 가장 쉬운 길과 공식 런처에서 동작시키는 길 두 가지를 안내합니다.
+
+#### 5-A. 가장 쉬운 길: Prism Launcher 로 갈아타기 (선택)
+
+공식 런처 대신 무료 오픈소스 런처인 **Prism Launcher** 를 쓰면 클릭 몇 번으로 JavaCV를 라이브러리로 추가할 수 있습니다. 게임 자체는 같고, 정품 마인크래프트 계정으로 로그인하는 것도 동일합니다.
+
+1. https://prismlauncher.org/download/ 에서 다운로드 → 설치
+2. Prism에서 인스턴스 → 마인크래프트 26.1.2 + Fabric Loader 0.19.2 선택해서 생성
+3. 인스턴스 우클릭 → **Edit** → 왼쪽의 **Version** 탭 → **Add to Minecraft.jar** 버튼
+4. 아래 STEP 5-B 의 1번 항목에서 받은 JavaCV jar 5개를 한꺼번에 선택해서 추가
+5. **Launch** 로 실행
+
+이 방법이 가장 안정적이고 빠릅니다.
+
+#### 5-B. 공식 런처에서 동작시키기
+
+공식 런처를 계속 쓰고 싶다면 아래 절차를 따르세요.
+
+1. **JavaCV 1.5.13 다운로드**
+   - 다운로드 링크: https://github.com/bytedeco/javacv/releases/download/1.5.13/javacv-platform-1.5.13-bin.zip (2026-02-22 릴리스, FFmpeg 8.0.1 동봉)
+   - 압축을 풀고 `javacv-platform-1.5.13-bin` 폴더 안에서 **다음 jar 5개**를 골라 둡니다 (다른 파일은 안 씁니다):
+     - `javacv.jar`
+     - `javacpp.jar`
+     - 자신의 OS에 맞는 **javacpp 네이티브 jar** (이게 빠지면 검은 화면 — JNI bridge `jnijavacpp` 로딩에 꼭 필요):
+       - Windows 64bit: `javacpp-1.5.13-windows-x86_64.jar`
+       - macOS Intel: `javacpp-1.5.13-macosx-x86_64.jar`
+       - macOS Apple Silicon (M1/M2/M3/M4): `javacpp-1.5.13-macosx-arm64.jar`
+       - Linux 64bit: `javacpp-1.5.13-linux-x86_64.jar`
+     - `ffmpeg.jar`
+     - 자신의 OS에 맞는 **ffmpeg 네이티브 jar**:
+       - Windows 64bit: `ffmpeg-8.0.1-1.5.13-windows-x86_64.jar`
+       - macOS Intel: `ffmpeg-8.0.1-1.5.13-macosx-x86_64.jar`
+       - macOS Apple Silicon (M1/M2/M3/M4): `ffmpeg-8.0.1-1.5.13-macosx-arm64.jar`
+       - Linux 64bit: `ffmpeg-8.0.1-1.5.13-linux-x86_64.jar`
+
+2. **이 5개 jar 를 게임이 읽도록 등록**
+   - 가장 안전한 위치: `.minecraft/libraries/javacv/` 폴더를 새로 만들고 5개 jar를 거기에 복사하세요. (긴 파일명이 부담스러우면 `javacpp-1.5.13-windows-x86_64.jar` → `javacpp-windows-x86_64.jar`, `ffmpeg-8.0.1-1.5.13-windows-x86_64.jar` → `ffmpeg-windows-x86_64.jar` 식으로 짧게 rename해도 됩니다. 아래 예시는 짧은 이름 기준.)
+   - 그 다음, 공식 런처에서 fabric 프로필 옆 **편집** 또는 **설치 설정** → 화면 아래쪽 **"JVM 인수"** (Java arguments) 칸을 켜고 기존 인수 **끝**에 한 칸 띄우고 다음 한 줄을 추가합니다.
+
+     ⚠ **반드시 절대경로(`C:\Users\...`)로 적어주세요.** 마인크래프트 공식 런처는 JVM 인수의 `%APPDATA%`·`%USERPROFILE%` 같은 환경변수를 풀어주지 않고 글자 그대로 Java 에 넘깁니다. 그러면 boot classpath 가 빈 상태가 되어 영상이 안 나옵니다.
+
+     Windows (사용자명 `홍길동` 예시):
+     ```
+     -Xbootclasspath/a:C:\Users\홍길동\AppData\Roaming\.minecraft\libraries\javacv\javacv.jar;C:\Users\홍길동\AppData\Roaming\.minecraft\libraries\javacv\javacpp.jar;C:\Users\홍길동\AppData\Roaming\.minecraft\libraries\javacv\javacpp-windows-x86_64.jar;C:\Users\홍길동\AppData\Roaming\.minecraft\libraries\javacv\ffmpeg.jar;C:\Users\홍길동\AppData\Roaming\.minecraft\libraries\javacv\ffmpeg-windows-x86_64.jar
+     ```
+     (`C:\Users\<본인 윈도우 사용자명>\AppData\Roaming\` 부분을 본인 사용자 폴더로 바꾸세요. 윈도우키+R → `cmd` → `echo %APPDATA%` 로 정확한 경로 확인 가능.)
+
+     macOS (Apple Silicon 예시):
+     ```
+     -Xbootclasspath/a:/Users/사용자이름/Library/Application Support/minecraft/libraries/javacv/javacv.jar:/Users/사용자이름/Library/Application Support/minecraft/libraries/javacv/javacpp.jar:/Users/사용자이름/Library/Application Support/minecraft/libraries/javacv/javacpp-macosx-arm64.jar:/Users/사용자이름/Library/Application Support/minecraft/libraries/javacv/ffmpeg.jar:/Users/사용자이름/Library/Application Support/minecraft/libraries/javacv/ffmpeg-macosx-arm64.jar
+     ```
+
+     Linux:
+     ```
+     -Xbootclasspath/a:/home/사용자이름/.minecraft/libraries/javacv/javacv.jar:/home/사용자이름/.minecraft/libraries/javacv/javacpp.jar:/home/사용자이름/.minecraft/libraries/javacv/javacpp-linux-x86_64.jar:/home/사용자이름/.minecraft/libraries/javacv/ffmpeg.jar:/home/사용자이름/.minecraft/libraries/javacv/ffmpeg-linux-x86_64.jar
+     ```
+
+     주의:
+     - Windows는 jar 사이를 **세미콜론(`;`)** 으로 구분합니다.
+     - macOS/Linux는 **콜론(`:`)** 으로 구분합니다.
+     - 경로에 띄어쓰기가 있으면(특히 macOS의 `Application Support`) 전체 인수를 큰따옴표로 감싸세요.
+     - `사용자이름` 부분은 실제 자신의 사용자 폴더 이름으로 바꾸세요.
+     - `javacpp-...` 와 `ffmpeg-...` 부분의 jar 이름은 OS에 맞춰 1번에서 고른 그 파일명 그대로 적습니다 (zip 안에는 `javacpp-1.5.13-windows-x86_64.jar`, `ffmpeg-8.0.1-1.5.13-windows-x86_64.jar` 같은 긴 이름으로 들어 있고, 위 예시는 짧게 rename한 것 기준입니다).
+     - **5개 모두** 적어야 합니다. `javacpp-<os>.jar` (네이티브) 가 빠지면 JNI bridge 가 로딩 안 돼서 영상이 검게만 보입니다.
+
+3. 저장 후 **플레이** 를 누르면 영상이 재생됩니다.
+
+> 절차가 너무 번거롭다고 느끼면 **5-A 의 Prism Launcher** 를 권장합니다. 동일한 jar 를 클릭으로 끌어다 놓기만 하면 끝납니다.
+
+### STEP 6. 잘 설치됐는지 확인
+
+게임 안에서 채팅창에 `/videostick` 을 입력하세요. 정상이라면:
+
+- 인벤토리에 **비디오 스틱** 아이템이 들어옵니다 (보라/검정 missing-texture 가 아니라 작대기 모양 아이콘).
+- 보라/검정 missing texture 가 나오면 **STEP 4** 에서 이전 버전 jar(`video_player-0.4.0.jar` / `0.4.1.jar` 등)가 mods 폴더에 같이 남아있는 경우입니다. 다 지우고 `0.4.7` 만 남기고 다시 시작하세요. (0.4.1 이하는 Fabric 26.1.2 model 로더가 unprefixed `item/generated` parent 를 거부해서 스틱 아이콘이 missing-model 큐브로 보입니다 — 0.4.2 에서 수정됨.)
+
+---
+
+## 사용법
+
+### 영상 배치
+
+1. 비디오 스틱을 손에 들고, 영상을 띄우고 싶은 벽/바닥/천장 블록을 **우클릭**.
+2. 열린 GUI 에 영상 URL, 가로(W), 세로(H), 반복 여부, 자동재생 여부를 입력.
+3. **클릭한 그 블록의 면** 이 영상의 왼쪽 아래 모서리가 되고, 오른쪽으로 W블록, 위로 H블록 만큼 영상이 펼쳐집니다.
+
+### 영상 수정 / 삭제
+
+- 이미 영상이 걸린 면을 다시 **우클릭** → GUI 재오픈, 내용 수정 가능
+- 영상 삭제: **쉬프트(Shift)** 누른 상태로 그 면을 **좌클릭**
+
+### URL 조건
+
+- `http://` 또는 `https://` URL만 됩니다 (`file://`, 로컬 파일 X)
+- 길이 256자 이하
+- FFmpeg 가 디코드 가능한 형식이면 됩니다 — mp4, webm, mkv, mov 등
+- 인증 토큰이 URL 에 들어 있으면 그 상태로 저장되니 공유 주의
+
+### 명령어
+
+| 명령 | 설명 |
+| --- | --- |
+| `/videostick` | 비디오 스틱 아이템을 인벤토리에 지급 |
+| `/videoplace <pos> <facing> <w> <h> <url>` | 좌표에 영상 앵커를 즉시 배치 |
+| `/videodelete <pos>` | 좌표의 영상 앵커 제거 |
+| `/videomute <pos> <on\|off>` | 영상의 음소거 켜고/끄기 |
+| `/videopreload <url>` | URL 을 미리 받아 디스크 캐시에 저장 (자세한 내용은 아래) |
+
+`/videoplace`, `/videodelete`, `/videomute`, `/videopreload` 는 기본적으로 OP(권한 레벨 2) 가 필요하므로 **커맨드 블럭에서도 그대로 호출 가능합니다**. 커맨드 블럭은 기본이 권한 레벨 2 라 별도 설정 없이 동작합니다.
+
+### `/videopreload` — 영상 미리 로딩 (스터터 제거)
+
+스트리밍 URL 을 라이브로 받으면서 재생하면 네트워크가 잠깐 느려질 때 끊김이 생깁니다. `/videopreload <url>` 을 미리 한번 실행하면 클라이언트가 백그라운드에서 URL 을 통째로 다운로드해서 `.minecraft/video_player_cache/` 폴더에 저장해 두고, 같은 URL 로 영상이 재생될 때 인터넷이 아니라 그 로컬 파일을 사용합니다 (= 끊김 없음).
+
+```
+/videopreload https://video.example.com/foo.mp4
 ```

-산출물: `build/libs/video_player-<version>.jar`
+특징:

-## 현재 진행도
+- **커맨드 블럭에서 사용 가능** — 예: 압력판 → 커맨드 블럭 `/videopreload <url>` 으로 트리거하면 플레이어가 영상 영역에 다가가기 전에 미리 다운로드 시작
+- 명령은 서버에서 실행되지만, 다운로드는 각 **클라이언트**(접속해 있는 모든 플레이어)가 자기 PC 에 받습니다
+- 이미 받아둔 URL 은 재요청해도 다시 다운로드 안 함 (URL 의 SHA-256 으로 캐싱)
+- 한 파일당 상한 512 MB
+- 캐시 폴더가 너무 커지면 직접 `.minecraft/video_player_cache/` 안의 파일을 삭제해도 됩니다 (그러면 다음 사용 시 다시 받아옴)

-이 저장소는 SPEC §10 마일스톤을 순차적으로 채우는 중입니다.
+> 영상 삭제 시 소리가 안 멎던 문제는 0.4.4 에서 수정되었습니다 (앵커 블록이 사라지면 디코더 / 오디오 라인을 즉시 강제 종료). 0.4.5 에서는 `BLOCK_ENTITY_UNLOAD` 이벤트가 누락되는 엣지케이스를 대비해 매 틱마다 BE 존재를 한 번 더 검증합니다.

- **M1 — 스캐폴드** (현재): Fabric 모드 골격, 비디오 앵커 블록/엔티티 등록, 비디오 스틱 아이템, `/videoStick` 명령.
- M2 — 정적 렌더
- M3 — JavaCV mp4 재생
- M4 — GUI / 네트워크
- M5 — 좌클릭 삭제 + `/videoPlace`, `/videoDelete`
- M6 — 오디오 + 거리감 + Mute(소리 on/off)
- M7 — WaterMedia 백엔드 + 자동 선택
- M8 — Stonecutter 멀티버전
+> 0.4.5 부터 다운로드 시작 / 완료 / 실패가 채팅창에 표시됩니다. 커맨드블럭으로 `/videopreload` 후 `/videoplace` 를 이어 실행할 때는 `[videopreload] 완료` 메시지를 본 뒤에 재생해야 로컬 파일에서 재생됩니다 (그 전에 재생하면 일반 스트리밍으로 떨어집니다).
+
+> 0.4.5 부터 오디오 거리 감쇠가 **판때기 중앙**을 기준으로 계산됩니다. 예전엔 앵커 블록(보통 화면 모서리)을 기준으로 측정해서 큰 화면일수록 소리가 한쪽에서 들리는 느낌이었습니다.
+
+### 서버 config 로 자동 프리로드 (0.4.6+)
+
+서버에 모드를 넣고 한 번 실행하면 `<서버폴더>/config/video_player.json` 가 자동 생성됩니다. 이 파일에 자주 쓰는 영상 URL 을 적어두면, 플레이어가 접속할 때마다 서버가 자동으로 그 URL 들의 프리로드 요청을 보냅니다 (= `/videopreload` 를 사람마다 친 것과 같음).
+
+기본 생성된 파일 예시:
+
+```json
+{
+  "_comment": "preload_urls: HTTP(S) video URLs broadcast to every player on join. ...",
+  "preload_urls": []
+}
+```
+
+사용 예시 — 인트로 영상과 BGM 영상을 모든 접속자가 미리 받도록:
+
+```json
+{
+  "preload_urls": [
+    "https://video.example.com/intro.mp4",
+    "https://video.example.com/bgm-loop.webm"
+  ]
+}
+```
+
+규칙:
+
+- 각 URL 은 `http://` 또는 `https://` 시작, 256자 이하 (그 외는 무시되고 서버 로그에 WARN)
+- 파일 수정 후 적용하려면 **서버 재시작** 이 필요합니다 (config 는 시작 시 1회만 로딩)
+- 접속한 플레이어 화면에는 `/videopreload` 와 동일한 `[videopreload] 다운로드 시작 / 완료` 채팅 메시지가 보입니다
+- 이미 캐시된 URL 은 다시 다운로드하지 않습니다 (SHA-256 캐시 키)
+- 싱글플레이는 자체적으로 통합 서버를 띄우므로, 통합 서버의 config 폴더(`<게임폴더>/config/video_player.json`)에도 같은 효과로 동작합니다
+
+---
+
+## 알려진 이슈
+
+- JavaCV가 안 잡혀있으면 영상 자리만 잡힐 뿐 검게 보입니다. 로그 파일(`.minecraft/logs/latest.log`)에서 `JavaCV not on classpath` WARN 또는 `JavaCV decode error: ...UnsatisfiedLinkError... jnijavacpp` 메시지로 확인 가능합니다. 후자는 `javacpp-<os>.jar` 네이티브 jar 가 빠진 케이스입니다 (STEP 5-B 1번의 5개 jar 모두 등록되어야 함).
+- 0.3.x 이하 버전에서 만든 영상은 새 버전(0.4.x) 에서 보이지 않으니 다시 배치해야 합니다.
+
+---
+
+## 개발자용 빌드
+
+```sh
+JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew build
+```
+
+산출물: `build/libs/video_player-0.4.7.jar`
+
+JavaCV를 직접 의존성으로 가져오는 경우의 Maven 좌표:
+```
+org.bytedeco:javacv-platform:1.5.13
+```
--- a/build.gradle
+++ b/build.gradle
@@ -1,5 +1,5 @@
 plugins {
-    id 'fabric-loom' version '1.16.2'
+    id 'net.fabricmc.fabric-loom' version "${loom_version}"
    id 'maven-publish'
    id 'java'
 }
@@ -16,33 +16,41 @@ repositories {
    maven { url = 'https://maven.fabricmc.net/' }
 }

+loom {
+    // Intentionally empty — MC 26.1+ ships unobfuscated, so the new loom does not remap.
+}
+
 dependencies {
+    // No mappings dep — Mojang ships official names since 26.1, intermediary is gone.
    minecraft "com.mojang:minecraft:${project.minecraft_version}"
-    mappings "net.fabricmc:yarn:${project.yarn_mappings}:v2"
-    modImplementation "net.fabricmc:fabric-loader:${project.loader_version}"
-    modImplementation "net.fabricmc.fabric-api:fabric-api:${project.fabric_version}"
+
+    implementation "net.fabricmc:fabric-loader:${project.loader_version}"
+    implementation "net.fabricmc.fabric-api:fabric-api:${project.fabric_version}"
 }

 processResources {
    inputs.property "version", project.version
    inputs.property "mod_id", project.mod_id
+    inputs.property "minecraft_version", project.minecraft_version

    filesMatching("fabric.mod.json") {
-        expand "version": project.version, "mod_id": project.mod_id
+        expand "version": project.version,
+               "mod_id": project.mod_id,
+               "target_minecraft": "~${project.minecraft_version}"
    }
 }

 tasks.withType(JavaCompile).configureEach {
-    it.options.release = 21
+    it.options.release = 25
 }

 java {
    withSourcesJar()
-    sourceCompatibility = JavaVersion.VERSION_21
-    targetCompatibility = JavaVersion.VERSION_21
+    sourceCompatibility = JavaVersion.VERSION_25
+    targetCompatibility = JavaVersion.VERSION_25

    toolchain {
-        languageVersion = JavaLanguageVersion.of(21)
+        languageVersion = JavaLanguageVersion.of(25)
    }
 }

--- a/gradle.properties
+++ b/gradle.properties
@@ -1,14 +1,16 @@
 org.gradle.jvmargs=-Xmx2G
 org.gradle.parallel=true
+# Config cache disabled — new loom + IntelliJ aren't fully compatible yet
+org.gradle.configuration-cache=false

 # Mod
 mod_id=video_player
-mod_version=0.1.0
+mod_version=0.4.7
 maven_group=com.ejclaw.videoplayer
 archives_base_name=video_player

-# Minecraft / Fabric (1.21.6)
-minecraft_version=1.21.6
-yarn_mappings=1.21.6+build.1
+# Minecraft / Fabric (26.1.2 — single target, intermediary/Yarn retired)
+minecraft_version=26.1.2
 loader_version=0.19.2
-fabric_version=0.120.1+1.21.6
+loom_version=1.16-SNAPSHOT
+fabric_version=0.149.0+26.1.2
--- a/src/main/java/com/ejclaw/videoplayer/VideoPlayerClient.java
+++ b/src/main/java/com/ejclaw/videoplayer/VideoPlayerClient.java
@@ -1,15 +1,104 @@
 package com.ejclaw.videoplayer;

+import com.ejclaw.videoplayer.block.VideoAnchorBlockEntity;
+import com.ejclaw.videoplayer.client.net.ClientNetworking;
+import com.ejclaw.videoplayer.client.playback.VideoPlayback;
+import com.ejclaw.videoplayer.client.render.VideoAnchorRenderer;
+import com.ejclaw.videoplayer.item.VideoStickItem;
+import com.ejclaw.videoplayer.net.DeleteAnchorPayload;
+import com.ejclaw.videoplayer.registry.VideoPlayerBlockEntities;
 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.ClientTickEvents;
+import net.fabricmc.fabric.api.client.networking.v1.ClientPlayNetworking;
+import net.fabricmc.fabric.api.client.rendering.v1.BlockEntityRendererRegistry;
+import net.fabricmc.fabric.api.client.rendering.v1.level.LevelRenderEvents;
+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.world.InteractionResult;
+import net.minecraft.world.phys.Vec3;

@Environment(EnvType.CLIENT)
 public class VideoPlayerClient implements ClientModInitializer {
+
    @Override
    public void onInitializeClient() {
-        // M2+: BlockEntityRendererFactories.register(...)
-        // M5+: AttackBlockCallback for left-click delete
-        VideoPlayerMod.LOG.info("[{}] client initialized (M1 scaffold)", VideoPlayerMod.MOD_ID);
+        ClientNetworking.register();
+
+        BlockEntityRendererRegistry.register(
+            VideoPlayerBlockEntities.VIDEO_ANCHOR,
+            VideoAnchorRenderer::new
+        );
+
+        AttackBlockCallback.EVENT.register((player, level, hand, pos, direction) -> {
+            if (!level.isClientSide()) return InteractionResult.PASS;
+            if (!(player.getMainHandItem().getItem() instanceof VideoStickItem)) return InteractionResult.PASS;
+            // The anchor itself is invisible / non-collidable so the player cannot left-click it
+            // directly. Sneak + left-click on the wall the video sits on → delete the anchor in
+            // the adjacent air block.
+            if (player.isShiftKeyDown()) {
+                BlockPos anchorPos = pos.relative(direction);
+                if (level.getBlockEntity(anchorPos) instanceof VideoAnchorBlockEntity) {
+                    ClientPlayNetworking.send(new DeleteAnchorPayload(anchorPos));
+                    return InteractionResult.SUCCESS;
+                }
+            }
+            // Legacy / safety: if the player somehow targets the anchor block directly.
+            if (level.getBlockEntity(pos) instanceof VideoAnchorBlockEntity) {
+                ClientPlayNetworking.send(new DeleteAnchorPayload(pos));
+                return InteractionResult.SUCCESS;
+            }
+            return InteractionResult.PASS;
+        });
+
+        // Pump frame uploads on every render frame (60+Hz) rather than every client tick
+        // (20Hz). At 24fps source, a 20Hz pump can skip a frame whenever a tick window happens
+        // to miss the decode boundary, producing visible micro-stutter even when frames are
+        // ready. Polling at render rate lets the texture latch as soon as a frame is decoded.
+        LevelRenderEvents.START_MAIN.register(ctx -> VideoPlayback.tick());
+
+        // Distance-gain math is cheap and only audible state — 20Hz is plenty and avoids
+        // recomputing it on every render frame.
+        ClientTickEvents.END_CLIENT_TICK.register(VideoPlayerClient::updateDistanceGains);
+
+        ClientTickEvents.END_LEVEL_TICK.register(world -> {
+            // no-op for now
+        });
+
+        // When an anchor block is deleted (shift+left-click, /videodelete) or its chunk
+        // unloads (player walks away), Minecraft removes the block entity client-side. Hook
+        // that to stop the decode worker and audio line — otherwise VideoPlayback.ENTRIES
+        // keeps holding the backend and the sound keeps playing.
+        ClientBlockEntityEvents.BLOCK_ENTITY_UNLOAD.register((blockEntity, level) -> {
+            if (blockEntity instanceof VideoAnchorBlockEntity) {
+                VideoPlayback.stop(blockEntity.getBlockPos());
+            }
+        });
+
+        VideoPlayerMod.LOG.info("[{}] client initialized", VideoPlayerMod.MOD_ID);
+    }
+
+    /**
+     * SPEC §6 — recompute per-anchor audio gain from player distance every tick.
+     * 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.
+     */
+    private static void updateDistanceGains(Minecraft client) {
+        LocalPlayer p = client.player;
+        if (p == null || client.level == null) return;
+        Vec3 eye = p.getEyePosition();
+        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;
+            VideoPlayback.setGain(pos, gain);
+        }
    }
 }
--- a/src/main/java/com/ejclaw/videoplayer/VideoPlayerConfig.java
+++ b/src/main/java/com/ejclaw/videoplayer/VideoPlayerConfig.java
@@ -0,0 +1,99 @@
+package com.ejclaw.videoplayer;
+
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParser;
+import net.fabricmc.loader.api.FabricLoader;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Server-side mod config, stored at {@code <gameDir>/config/video_player.json}.
+ *
+ * <p>Format (auto-generated on first start):
+ * <pre>{@code
+ * {
+ *   // List of HTTP(S) video URLs that the server will tell every player to preload
+ *   // into their local video_player_cache/ folder when they join. Identical to running
+ *   // /videopreload <url> for each joining player.
+ *   "preload_urls": [
+ *     "https://example.com/intro.mp4"
+ *   ]
+ * }
+ * }</pre>
+ *
+ * <p>Why a list and not a dedicated tool: the same {@link
+ * com.ejclaw.videoplayer.net.PreloadPayload} that powers {@code /videopreload} is reused, so the
+ * client-side cache, chat feedback, and {@code /videoplace} → cache lookup paths all behave
+ * identically for config-driven and command-driven preloads.
+ */
+public final class VideoPlayerConfig {
+    private VideoPlayerConfig() {}
+
+    private static final String FILE_NAME = "video_player.json";
+    private static volatile List<String> PRELOAD_URLS = Collections.emptyList();
+
+    /** Load (or create) the config file. Called once during mod initialization. */
+    public static void load() {
+        Path path = FabricLoader.getInstance().getConfigDir().resolve(FILE_NAME);
+        try {
+            if (!Files.exists(path)) {
+                writeDefault(path);
+                VideoPlayerMod.LOG.info("[{}] created default config at {}",
+                    VideoPlayerMod.MOD_ID, path);
+                PRELOAD_URLS = Collections.emptyList();
+                return;
+            }
+            String raw = Files.readString(path, StandardCharsets.UTF_8);
+            JsonObject json = JsonParser.parseString(raw).getAsJsonObject();
+            List<String> urls = new ArrayList<>();
+            if (json.has("preload_urls") && json.get("preload_urls").isJsonArray()) {
+                json.getAsJsonArray("preload_urls").forEach(el -> {
+                    if (el.isJsonPrimitive() && el.getAsJsonPrimitive().isString()) {
+                        String u = el.getAsString().trim();
+                        if (!u.isEmpty() && (u.startsWith("http://") || u.startsWith("https://"))
+                            && u.length() <= 256) {
+                            urls.add(u);
+                        } else if (!u.isEmpty()) {
+                            VideoPlayerMod.LOG.warn(
+                                "[{}] config: ignoring invalid preload url '{}' (must be http/https, ≤256 chars)",
+                                VideoPlayerMod.MOD_ID, u);
+                        }
+                    }
+                });
+            }
+            PRELOAD_URLS = Collections.unmodifiableList(urls);
+            VideoPlayerMod.LOG.info("[{}] config loaded: {} preload url(s)",
+                VideoPlayerMod.MOD_ID, urls.size());
+        } catch (Throwable t) {
+            VideoPlayerMod.LOG.warn("[{}] failed to read config {}: {} — using empty list",
+                VideoPlayerMod.MOD_ID, path, t.toString());
+            PRELOAD_URLS = Collections.emptyList();
+        }
+    }
+
+    /** URLs to push to each joining player. Never null; possibly empty. */
+    public static List<String> preloadUrls() {
+        return PRELOAD_URLS;
+    }
+
+    private static void writeDefault(Path path) throws IOException {
+        Files.createDirectories(path.getParent());
+        // Hand-rolled rather than Gson-serialized so we can carry a `_comment` field that
+        // explains the format directly inside the file.
+        JsonObject root = new JsonObject();
+        root.addProperty("_comment",
+            "preload_urls: HTTP(S) video URLs broadcast to every player on join. "
+                + "Equivalent to running /videopreload <url> per joiner. Max 256 chars per url.");
+        root.add("preload_urls", new com.google.gson.JsonArray());
+        Gson gson = new GsonBuilder().setPrettyPrinting().disableHtmlEscaping().create();
+        Files.writeString(path, gson.toJson(root), StandardCharsets.UTF_8);
+    }
+}
--- a/src/main/java/com/ejclaw/videoplayer/VideoPlayerMod.java
+++ b/src/main/java/com/ejclaw/videoplayer/VideoPlayerMod.java
@@ -1,11 +1,19 @@
 package com.ejclaw.videoplayer;

+import com.ejclaw.videoplayer.command.VideoDeleteCommand;
+import com.ejclaw.videoplayer.command.VideoMuteCommand;
+import com.ejclaw.videoplayer.command.VideoPlaceCommand;
+import com.ejclaw.videoplayer.command.VideoPreloadCommand;
 import com.ejclaw.videoplayer.command.VideoStickCommand;
+import com.ejclaw.videoplayer.net.PreloadPayload;
+import com.ejclaw.videoplayer.net.VideoPlayerNetwork;
 import com.ejclaw.videoplayer.registry.VideoPlayerBlockEntities;
 import com.ejclaw.videoplayer.registry.VideoPlayerBlocks;
 import com.ejclaw.videoplayer.registry.VideoPlayerItems;
 import net.fabricmc.api.ModInitializer;
 import net.fabricmc.fabric.api.command.v2.CommandRegistrationCallback;
+import net.fabricmc.fabric.api.networking.v1.ServerPlayConnectionEvents;
+import net.fabricmc.fabric.api.networking.v1.ServerPlayNetworking;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;

@@ -19,10 +27,32 @@ public class VideoPlayerMod implements ModInitializer {
        VideoPlayerBlockEntities.register();
        VideoPlayerItems.register();

+        VideoPlayerNetwork.registerPayloadTypes();
+        VideoPlayerNetwork.registerServerReceivers();
+
+        VideoPlayerConfig.load();
+
        CommandRegistrationCallback.EVENT.register((dispatcher, registryAccess, env) -> {
            VideoStickCommand.register(dispatcher);
+            VideoPlaceCommand.register(dispatcher);
+            VideoDeleteCommand.register(dispatcher);
+            VideoMuteCommand.register(dispatcher);
+            VideoPreloadCommand.register(dispatcher);
        });

-        LOG.info("[{}] initialized (M1 scaffold)", MOD_ID);
+        // When a player finishes joining, push every preload URL from the config so their
+        // client kicks off the background download. Reuses the same PreloadPayload that
+        // /videopreload sends, so the client-side caching path is identical.
+        ServerPlayConnectionEvents.JOIN.register((handler, sender, server) -> {
+            java.util.List<String> urls = VideoPlayerConfig.preloadUrls();
+            if (urls.isEmpty()) return;
+            for (String url : urls) {
+                ServerPlayNetworking.send(handler.getPlayer(), new PreloadPayload(url));
+            }
+            LOG.info("[{}] sent {} config preload(s) to {}",
+                MOD_ID, urls.size(), handler.getPlayer().getName().getString());
+        });
+
+        LOG.info("[{}] initialized", MOD_ID);
    }
 }
--- a/src/main/java/com/ejclaw/videoplayer/block/VideoAnchorBlock.java
+++ b/src/main/java/com/ejclaw/videoplayer/block/VideoAnchorBlock.java
@@ -1,28 +1,90 @@
 package com.ejclaw.videoplayer.block;

+import com.ejclaw.videoplayer.item.VideoStickItem;
+import com.ejclaw.videoplayer.net.OpenScreenPayload;
 import com.mojang.serialization.MapCodec;
-import net.minecraft.block.AbstractBlock;
-import net.minecraft.block.Block;
-import net.minecraft.block.BlockEntityProvider;
-import net.minecraft.block.BlockState;
-import net.minecraft.block.BlockWithEntity;
-import net.minecraft.block.entity.BlockEntity;
-import net.minecraft.util.math.BlockPos;
+import net.fabricmc.fabric.api.networking.v1.ServerPlayNetworking;
+import net.minecraft.core.BlockPos;
+import net.minecraft.server.level.ServerPlayer;
+import net.minecraft.world.InteractionHand;
+import net.minecraft.world.InteractionResult;
+import net.minecraft.world.entity.player.Player;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.level.BlockGetter;
+import net.minecraft.world.level.Level;
+import net.minecraft.world.level.block.BaseEntityBlock;
+import net.minecraft.world.level.block.RenderShape;
+import net.minecraft.world.level.block.entity.BlockEntity;
+import net.minecraft.world.level.block.state.BlockBehaviour;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.phys.BlockHitResult;
+import net.minecraft.world.phys.shapes.CollisionContext;
+import net.minecraft.world.phys.shapes.Shapes;
+import net.minecraft.world.phys.shapes.VoxelShape;

-public class VideoAnchorBlock extends BlockWithEntity implements BlockEntityProvider {
-    public static final MapCodec<VideoAnchorBlock> CODEC = createCodec(VideoAnchorBlock::new);
+/**
+ * Anchor block — invisible, non-collidable host for {@link VideoAnchorBlockEntity}.
+ *
+ * <p>The block exists only so a {@link BlockEntity} can be attached to a position; visually it is
+ * completely empty (no model, no selection outline, no collision). The video itself is drawn by
+ * {@link com.ejclaw.videoplayer.client.render.VideoAnchorRenderer} flush against the wall the
+ * player clicked, not as a textured surface on this block.
+ */
+public class VideoAnchorBlock extends BaseEntityBlock {
+    public static final MapCodec<VideoAnchorBlock> CODEC = simpleCodec(VideoAnchorBlock::new);

-    public VideoAnchorBlock(AbstractBlock.Settings settings) {
-        super(settings);
+    public VideoAnchorBlock(BlockBehaviour.Properties properties) {
+        super(properties);
    }

    @Override
-    protected MapCodec<? extends BlockWithEntity> getCodec() {
+    protected MapCodec<? extends BaseEntityBlock> codec() {
        return CODEC;
    }

    @Override
-    public BlockEntity createBlockEntity(BlockPos pos, BlockState state) {
+    public BlockEntity newBlockEntity(BlockPos pos, BlockState state) {
        return new VideoAnchorBlockEntity(pos, state);
    }
+
+    @Override
+    protected RenderShape getRenderShape(BlockState state) {
+        return RenderShape.INVISIBLE;
+    }
+
+    @Override
+    protected VoxelShape getShape(BlockState state, BlockGetter level, BlockPos pos, CollisionContext ctx) {
+        return Shapes.empty();
+    }
+
+    @Override
+    protected VoxelShape getCollisionShape(BlockState state, BlockGetter level, BlockPos pos, CollisionContext ctx) {
+        return Shapes.empty();
+    }
+
+    @Override
+    protected VoxelShape getOcclusionShape(BlockState state) {
+        return Shapes.empty();
+    }
+
+    @Override
+    protected boolean propagatesSkylightDown(BlockState state) {
+        return true;
+    }
+
+    @Override
+    protected InteractionResult useItemOn(ItemStack stack, BlockState state, Level level,
+                                          BlockPos pos, Player player, InteractionHand hand,
+                                          BlockHitResult hit) {
+        if (!(stack.getItem() instanceof VideoStickItem)) {
+            return InteractionResult.PASS;
+        }
+        if (level.isClientSide()) return InteractionResult.SUCCESS;
+        if (!(player instanceof ServerPlayer sp)) return InteractionResult.PASS;
+        if (level.getBlockEntity(pos) instanceof VideoAnchorBlockEntity be) {
+            ServerPlayNetworking.send(sp, new OpenScreenPayload(pos, be.toNbt()));
+            return InteractionResult.SUCCESS;
+        }
+        return InteractionResult.PASS;
+    }
 }
--- a/src/main/java/com/ejclaw/videoplayer/block/VideoAnchorBlockEntity.java
+++ b/src/main/java/com/ejclaw/videoplayer/block/VideoAnchorBlockEntity.java
@@ -1,14 +1,19 @@
 package com.ejclaw.videoplayer.block;

 import com.ejclaw.videoplayer.registry.VideoPlayerBlockEntities;
-import net.minecraft.block.BlockState;
-import net.minecraft.block.entity.BlockEntity;
-import net.minecraft.util.math.BlockPos;
-import net.minecraft.util.math.Direction;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Direction;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.world.level.block.entity.BlockEntity;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.storage.ValueInput;
+import net.minecraft.world.level.storage.ValueOutput;
+import net.minecraft.world.phys.Vec3;

 /**
- * M1 placeholder. Holds the runtime fields described in SPEC §3.1; NBT persistence
- * (ReadView/WriteView in 1.21.6) lands in M3/M4 alongside the playback and GUI work.
+ * Anchor BE — holds per-block config that drives playback.
+ * NBT persistence uses 26.1's ValueInput/ValueOutput.
+ * Network sync uses {@link #toNbt()} / {@link #fromNbt(CompoundTag)}.
 */
 public class VideoAnchorBlockEntity extends BlockEntity {
    private String url = "";
@@ -33,8 +38,119 @@ public class VideoAnchorBlockEntity extends BlockEntity {
    public boolean isMuted() { return muted; }
    public boolean isAutoplay() { return autoplay; }

-    public void setMuted(boolean muted) {
-        this.muted = muted;
-        markDirty();
+    public void setUrl(String url) { this.url = url == null ? "" : url; setChanged(); }
+    public void setWidth(int width) { this.width = clamp(width, 1, 32); setChanged(); }
+    public void setHeight(int height) { this.height = clamp(height, 1, 32); setChanged(); }
+    public void setFacing(Direction facing) { this.facing = facing == null ? Direction.NORTH : facing; setChanged(); }
+    public void setLoop(boolean loop) { this.loop = loop; setChanged(); }
+    public void setVolume(float volume) { this.volume = Math.max(0F, Math.min(1F, volume)); setChanged(); }
+    public void setMuted(boolean muted) { this.muted = muted; setChanged(); }
+    public void setAutoplay(boolean autoplay) { this.autoplay = autoplay; setChanged(); }
+
+    /** Apply server-validated config from an NBT (used by network handler). */
+    public void applyFromNbt(CompoundTag nbt) {
+        fromNbt(nbt);
+        setChanged();
+    }
+
+    /**
+     * World-space center of the rendered panel. Used for distance-based audio attenuation so
+     * the sound source feels like it's coming from the middle of the screen, not the corner
+     * (anchor block). Geometry mirrors {@code VideoAnchorRenderer#submit}:
+     * the panel's bottom-left corner sits on the wall surface at
+     * {@code anchorCenter + (-0.5)*facing + (-0.5)*right + (-0.5)*up}, and the panel extends
+     * {@code width × height} blocks along {@code right} and {@code up}. So the center is
+     * {@code anchorCenter + (w/2 - 0.5)*right + (h/2 - 0.5)*up + (-0.5)*facing}.
+     */
+    public Vec3 panelCenter() {
+        Vec3 right, up;
+        switch (facing) {
+            case NORTH -> { right = new Vec3(-1, 0,  0); up = new Vec3(0,  1, 0); }
+            case SOUTH -> { right = new Vec3( 1, 0,  0); up = new Vec3(0,  1, 0); }
+            case EAST  -> { right = new Vec3( 0, 0, -1); up = new Vec3(0,  1, 0); }
+            case WEST  -> { right = new Vec3( 0, 0,  1); up = new Vec3(0,  1, 0); }
+            case UP    -> { right = new Vec3( 1, 0,  0); up = new Vec3(0,  0, -1); }
+            case DOWN  -> { right = new Vec3( 1, 0,  0); up = new Vec3(0,  0,  1); }
+            default    -> { right = new Vec3( 1, 0,  0); up = new Vec3(0,  1,  0); }
+        }
+        Vec3 facingVec = new Vec3(facing.getStepX(), facing.getStepY(), facing.getStepZ());
+        BlockPos p = getBlockPos();
+        Vec3 anchorCenter = new Vec3(p.getX() + 0.5, p.getY() + 0.5, p.getZ() + 0.5);
+        double offR = width  / 2.0 - 0.5;
+        double offU = height / 2.0 - 0.5;
+        return anchorCenter
+            .add(right.scale(offR))
+            .add(up.scale(offU))
+            .add(facingVec.scale(-0.5));
+    }
+
+    /** Wire-format NBT used by SaveConfig/SyncAnchor payloads. */
+    public CompoundTag toNbt() {
+        CompoundTag nbt = new CompoundTag();
+        nbt.putString("url", url);
+        nbt.putInt("width", width);
+        nbt.putInt("height", height);
+        nbt.putString("facing", facing.getSerializedName());
+        nbt.putBoolean("loop", loop);
+        nbt.putFloat("volume", volume);
+        nbt.putBoolean("muted", muted);
+        nbt.putBoolean("autoplay", autoplay);
+        return nbt;
+    }
+
+    public void fromNbt(CompoundTag nbt) {
+        this.url = clampUrl(nbt.getStringOr("url", ""));
+        this.width = clamp(nbt.getIntOr("width", 1), 1, 32);
+        this.height = clamp(nbt.getIntOr("height", 1), 1, 32);
+        Direction d = directionFromName(nbt.getStringOr("facing", "north"));
+        this.facing = d == null ? Direction.NORTH : d;
+        this.loop = nbt.getBooleanOr("loop", true);
+        this.volume = Math.max(0F, Math.min(1F, nbt.getFloatOr("volume", 0.5F)));
+        this.muted = nbt.getBooleanOr("muted", false);
+        this.autoplay = nbt.getBooleanOr("autoplay", true);
+    }
+
+    @Override
+    protected void saveAdditional(ValueOutput out) {
+        super.saveAdditional(out);
+        out.putString("url", url);
+        out.putInt("width", width);
+        out.putInt("height", height);
+        out.putString("facing", facing.getSerializedName());
+        out.putBoolean("loop", loop);
+        out.putFloat("volume", volume);
+        out.putBoolean("muted", muted);
+        out.putBoolean("autoplay", autoplay);
+    }
+
+    @Override
+    protected void loadAdditional(ValueInput in) {
+        super.loadAdditional(in);
+        this.url = clampUrl(in.getStringOr("url", ""));
+        this.width = clamp(in.getIntOr("width", 1), 1, 32);
+        this.height = clamp(in.getIntOr("height", 1), 1, 32);
+        Direction d = directionFromName(in.getStringOr("facing", "north"));
+        this.facing = d == null ? Direction.NORTH : d;
+        this.loop = in.getBooleanOr("loop", true);
+        this.volume = Math.max(0F, Math.min(1F, in.getFloatOr("volume", 0.5F)));
+        this.muted = in.getBooleanOr("muted", false);
+        this.autoplay = in.getBooleanOr("autoplay", true);
+    }
+
+    private static Direction directionFromName(String name) {
+        if (name == null) return null;
+        for (Direction d : Direction.values()) {
+            if (d.getSerializedName().equalsIgnoreCase(name)) return d;
+        }
+        return null;
+    }
+
+    private static int clamp(int v, int lo, int hi) {
+        return Math.max(lo, Math.min(hi, v));
+    }
+
+    private static String clampUrl(String s) {
+        if (s == null) return "";
+        return s.length() > 256 ? s.substring(0, 256) : s;
    }
 }
--- a/src/main/java/com/ejclaw/videoplayer/client/gui/VideoConfigScreen.java
+++ b/src/main/java/com/ejclaw/videoplayer/client/gui/VideoConfigScreen.java
@@ -0,0 +1,139 @@
+package com.ejclaw.videoplayer.client.gui;
+
+import com.ejclaw.videoplayer.net.DeleteAnchorPayload;
+import com.ejclaw.videoplayer.net.SaveConfigPayload;
+import net.fabricmc.api.EnvType;
+import net.fabricmc.api.Environment;
+import net.fabricmc.fabric.api.client.networking.v1.ClientPlayNetworking;
+import net.minecraft.client.Minecraft;
+import net.minecraft.client.gui.components.AbstractSliderButton;
+import net.minecraft.client.gui.components.Button;
+import net.minecraft.client.gui.components.Checkbox;
+import net.minecraft.client.gui.components.EditBox;
+import net.minecraft.client.gui.screens.Screen;
+import net.minecraft.core.BlockPos;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.network.chat.Component;
+
+/** SPEC §4.3 — anchor config GUI. Opened by S2C {@code OpenScreenPayload}. */
+@Environment(EnvType.CLIENT)
+public class VideoConfigScreen extends Screen {
+    private final BlockPos pos;
+    private final CompoundTag initial;
+
+    private EditBox urlField;
+    private EditBox widthField;
+    private EditBox heightField;
+    private Checkbox loopBox;
+    private Checkbox muteBox;
+    private Checkbox autoplayBox;
+    private VolumeSlider volumeSlider;
+
+    public VideoConfigScreen(BlockPos pos, CompoundTag data) {
+        super(Component.literal("Video Anchor"));
+        this.pos = pos;
+        this.initial = data;
+    }
+
+    @Override
+    protected void init() {
+        int cx = this.width / 2;
+        int y  = 40;
+
+        urlField = new EditBox(this.font, cx - 150, y, 300, 20, Component.literal("URL"));
+        urlField.setMaxLength(256);
+        urlField.setValue(initial.getStringOr("url", ""));
+        addRenderableWidget(urlField);
+        y += 30;
+
+        widthField  = new EditBox(this.font, cx - 150, y, 60, 20, Component.literal("W"));
+        widthField.setMaxLength(2);
+        widthField.setValue(Integer.toString(initial.getIntOr("width", 1)));
+        addRenderableWidget(widthField);
+
+        heightField = new EditBox(this.font, cx - 80, y, 60, 20, Component.literal("H"));
+        heightField.setMaxLength(2);
+        heightField.setValue(Integer.toString(initial.getIntOr("height", 1)));
+        addRenderableWidget(heightField);
+
+        volumeSlider = new VolumeSlider(cx - 10, y, 160, 20,
+            Math.max(0F, Math.min(1F, initial.getFloatOr("volume", 0.5F))));
+        addRenderableWidget(volumeSlider);
+        y += 30;
+
+        loopBox = Checkbox.builder(Component.literal("Loop"), this.font)
+            .pos(cx - 150, y).selected(initial.getBooleanOr("loop", true)).build();
+        addRenderableWidget(loopBox);
+
+        muteBox = Checkbox.builder(Component.literal("Mute"), this.font)
+            .pos(cx - 60, y).selected(initial.getBooleanOr("muted", false)).build();
+        addRenderableWidget(muteBox);
+
+        autoplayBox = Checkbox.builder(Component.literal("Autoplay"), this.font)
+            .pos(cx + 30, y).selected(initial.getBooleanOr("autoplay", true)).build();
+        addRenderableWidget(autoplayBox);
+        y += 36;
+
+        addRenderableWidget(Button.builder(Component.literal("Save"), b -> save())
+            .bounds(cx - 150, y, 90, 20).build());
+        addRenderableWidget(Button.builder(Component.literal("Cancel"), b -> onClose())
+            .bounds(cx - 45, y, 90, 20).build());
+        addRenderableWidget(Button.builder(Component.literal("Delete"), b -> delete())
+            .bounds(cx + 60, y, 90, 20).build());
+    }
+
+    private void save() {
+        CompoundTag out = new CompoundTag();
+        out.putString("url", urlField.getValue());
+        out.putInt("width",  parseInt(widthField.getValue(), 1));
+        out.putInt("height", parseInt(heightField.getValue(), 1));
+        out.putString("facing", initial.getStringOr("facing", "north"));
+        out.putBoolean("loop", loopBox.selected());
+        out.putFloat("volume", volumeSlider.getVolume());
+        out.putBoolean("muted", muteBox.selected());
+        out.putBoolean("autoplay", autoplayBox.selected());
+        ClientPlayNetworking.send(new SaveConfigPayload(pos, out));
+        onClose();
+    }
+
+    private void delete() {
+        ClientPlayNetworking.send(new DeleteAnchorPayload(pos));
+        onClose();
+    }
+
+    @Override
+    public boolean isPauseScreen() { return false; }
+
+    @Override
+    public void onClose() {
+        Minecraft mc = this.minecraft != null ? this.minecraft : Minecraft.getInstance();
+        if (mc != null) mc.setScreen(null);
+    }
+
+    private static int parseInt(String s, int dflt) {
+        try { return Integer.parseInt(s); } catch (Exception e) { return dflt; }
+    }
+
+    private static final class VolumeSlider extends AbstractSliderButton {
+        VolumeSlider(int x, int y, int w, int h, float initial) {
+            super(x, y, w, h, Component.literal("Volume: " + pct(initial)), initial);
+            updateMessage();
+        }
+
+        float getVolume() { return (float) this.value; }
+
+        @Override
+        protected void updateMessage() {
+            setMessage(Component.literal("Volume: " + pct((float) this.value)));
+        }
+
+        @Override
+        protected void applyValue() {
+            updateMessage();
+        }
+
+        private static int pct(float v) {
+            return Math.round(v * 100F);
+        }
+    }
+}
--- a/src/main/java/com/ejclaw/videoplayer/client/net/ClientNetworking.java
+++ b/src/main/java/com/ejclaw/videoplayer/client/net/ClientNetworking.java
@@ -0,0 +1,44 @@
+package com.ejclaw.videoplayer.client.net;
+
+import com.ejclaw.videoplayer.block.VideoAnchorBlockEntity;
+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.OpenScreenPayload;
+import com.ejclaw.videoplayer.net.PreloadPayload;
+import com.ejclaw.videoplayer.net.SyncAnchorPayload;
+import net.fabricmc.api.EnvType;
+import net.fabricmc.api.Environment;
+import net.fabricmc.fabric.api.client.networking.v1.ClientPlayNetworking;
+import net.minecraft.client.Minecraft;
+
+/** Client-side S2C receivers for OpenScreen and SyncAnchor. */
+@Environment(EnvType.CLIENT)
+public final class ClientNetworking {
+    private ClientNetworking() {}
+
+    public static void register() {
+        ClientPlayNetworking.registerGlobalReceiver(OpenScreenPayload.TYPE, (payload, context) -> {
+            Minecraft mc = context.client();
+            mc.execute(() -> mc.setScreen(new VideoConfigScreen(payload.pos(), payload.data())));
+        });
+
+        ClientPlayNetworking.registerGlobalReceiver(SyncAnchorPayload.TYPE, (payload, context) -> {
+            Minecraft mc = context.client();
+            mc.execute(() -> {
+                if (mc.level == null) return;
+                if (mc.level.getBlockEntity(payload.pos()) instanceof VideoAnchorBlockEntity be) {
+                    be.applyFromNbt(payload.data());
+                    VideoPlayback.onConfigChanged(be);
+                }
+            });
+        });
+
+        // Server broadcasts a preload request to all clients; each client downloads to its
+        // own video_player_cache/ folder. Runs entirely off-thread, so we don't bounce through
+        // mc.execute() — VideoCache.preload() is itself non-blocking.
+        ClientPlayNetworking.registerGlobalReceiver(PreloadPayload.TYPE, (payload, context) -> {
+            VideoCache.preload(payload.url());
+        });
+    }
+}
--- a/src/main/java/com/ejclaw/videoplayer/client/playback/JavaCvBackend.java
+++ b/src/main/java/com/ejclaw/videoplayer/client/playback/JavaCvBackend.java
@@ -0,0 +1,309 @@
+package com.ejclaw.videoplayer.client.playback;
+
+import com.ejclaw.videoplayer.VideoPlayerMod;
+import net.fabricmc.api.EnvType;
+import net.fabricmc.api.Environment;
+
+import javax.sound.sampled.AudioFormat;
+import javax.sound.sampled.AudioSystem;
+import javax.sound.sampled.SourceDataLine;
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.nio.ByteBuffer;
+import java.nio.ByteOrder;
+import java.nio.ShortBuffer;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicReference;
+
+/**
+ * SPEC §5.3 — fallback mp4/http(s) backend driven by JavaCV's FFmpegFrameGrabber.
+ *
+ * <p>Video frames are decoded through {@code grab()}, audio samples are forced to interleaved
+ * signed 16-bit PCM ({@code AV_SAMPLE_FMT_S16}) and written to a {@link SourceDataLine} so that
+ * {@link #setVolume(float)} actually mutes / attenuates audible output. JavaCV is referenced
+ * entirely through reflection so that the mod jar stays loadable when the (large) JavaCV
+ * dependency isn't bundled — the backend just reports {@code !isReady()} until the runtime
+ * classpath contains {@code org.bytedeco.javacv.FFmpegFrameGrabber}.
+ */
+@Environment(EnvType.CLIENT)
+public class JavaCvBackend implements VideoBackend {
+    private static final String GRABBER_CLASS = "org.bytedeco.javacv.FFmpegFrameGrabber";
+    private static final String FRAME_CLASS   = "org.bytedeco.javacv.Frame";
+    private static final String CONVERTER_CLASS = "org.bytedeco.javacv.Java2DFrameConverter";
+    /** {@code AV_SAMPLE_FMT_S16} from {@code org.bytedeco.ffmpeg.global.avutil}. */
+    private static final int AV_SAMPLE_FMT_S16 = 1;
+
+    private final Object lock = new Object();
+    private Thread worker;
+    private final AtomicBoolean running = new AtomicBoolean(false);
+    private final AtomicBoolean paused  = new AtomicBoolean(false);
+    private final AtomicReference<ByteBuffer> latest = new AtomicReference<>();
+    private volatile int width = 0;
+    private volatile int height = 0;
+    private volatile float gain = 1.0F;
+    private volatile boolean loop = true;
+    private volatile boolean ready = false;
+    private volatile boolean closed = false;
+    /**
+     * Held in a field (not just a local) so {@link #close()} can call
+     * {@link SourceDataLine#stop()} / {@link SourceDataLine#flush()} from outside the worker
+     * thread to unblock any in-flight {@link SourceDataLine#write(byte[], int, int)} call.
+     * Without this, deleting an anchor while audio is buffered would leave the worker stuck
+     * in {@code write()} until the in-driver PCM buffer drained naturally, so the deleted
+     * video would keep audible for ~0.5 s after the anchor disappeared.
+     */
+    private volatile SourceDataLine audioLine;
+    /**
+     * Worker-side handle to the grabber. Held so {@link #close()} can yank it from another
+     * thread when {@code grab()} is blocked on a slow HTTP read.
+     */
+    private volatile Object grabberHandle;
+
+    @Override
+    public void play(String url, boolean loop) {
+        if (url == null || url.isEmpty()) return;
+        this.loop = loop;
+        synchronized (lock) {
+            stopWorker();
+            running.set(true);
+            paused.set(false);
+            worker = new Thread(() -> runLoop(url), "video_player-decode");
+            worker.setDaemon(true);
+            worker.start();
+        }
+    }
+
+    @Override
+    public void pause()  { paused.set(true); }
+    @Override
+    public void resume() { paused.set(false); }
+    @Override
+    public void setVolume(float g) { this.gain = Math.max(0F, Math.min(1F, g)); }
+    @Override
+    public boolean isReady() { return ready; }
+    @Override
+    public int videoWidth()  { return width; }
+    @Override
+    public int videoHeight() { return height; }
+
+    @Override
+    public ByteBuffer pollFrame() {
+        return latest.getAndSet(null);
+    }
+
+    @Override
+    public void close() {
+        closed = true;
+        stopWorker();
+    }
+
+    private void stopWorker() {
+        running.set(false);
+        // Unblock the audio sink so the worker's line.write() returns immediately instead of
+        // waiting for the in-driver PCM buffer to drain. Without this the audible tail of a
+        // deleted / unloaded anchor outlives the anchor by ~0.5 s.
+        SourceDataLine line = audioLine;
+        if (line != null) {
+            try { line.stop();  } catch (Throwable ignored) {}
+            try { line.flush(); } catch (Throwable ignored) {}
+        }
+        // Yank the grabber too so a blocked grab() inside an HTTP read returns promptly.
+        // JavaCV's close() is best-effort thread-safe — worst case we trip an AVERROR which
+        // the catch-all in runLoop swallows.
+        Object g = grabberHandle;
+        if (g != null) {
+            try { g.getClass().getMethod("close").invoke(g); } catch (Throwable ignored) {}
+        }
+        Thread t = worker;
+        worker = null;
+        if (t != null) t.interrupt();
+        ready = false;
+    }
+
+    /** Pure-reflection decode loop. Silent fallback if JavaCV isn't present. */
+    private void runLoop(String url) {
+        Object grabber = null;
+        SourceDataLine localAudioLine = null;
+        try {
+            Class<?> grabberCls = Class.forName(GRABBER_CLASS);
+            grabber = grabberCls.getConstructor(String.class).newInstance(url);
+            this.grabberHandle = grabber;
+            Method start  = grabberCls.getMethod("start");
+            Method stop   = grabberCls.getMethod("stop");
+            Method grab   = grabberCls.getMethod("grab");
+            Method getW   = grabberCls.getMethod("getImageWidth");
+            Method getH   = grabberCls.getMethod("getImageHeight");
+            Method getSampleRate    = grabberCls.getMethod("getSampleRate");
+            Method getAudioChannels = grabberCls.getMethod("getAudioChannels");
+            Method setOpt = grabberCls.getMethod("setOption", String.class, String.class);
+            Method setSampleFormat  = grabberCls.getMethod("setSampleFormat", int.class);
+
+            // HTTP(S) tuning for streaming URLs (webm via Range / chunked transfer).
+            // Lower timeouts → close() snaps shut fast when an anchor is deleted mid-stream;
+            // larger buffer/probe options → smoother playback when the upstream throttles.
+            try { setOpt.invoke(grabber, "rw_timeout",          "3000000");   } catch (Throwable ignored) {}
+            try { setOpt.invoke(grabber, "timeout",             "3000000");   } catch (Throwable ignored) {}
+            try { setOpt.invoke(grabber, "reconnect",           "1");         } catch (Throwable ignored) {}
+            try { setOpt.invoke(grabber, "reconnect_streamed",  "1");         } catch (Throwable ignored) {}
+            try { setOpt.invoke(grabber, "reconnect_at_eof",    "1");         } catch (Throwable ignored) {}
+            try { setOpt.invoke(grabber, "reconnect_delay_max", "2");         } catch (Throwable ignored) {}
+            // Bigger network read window so a transient stall doesn't starve the decoder.
+            try { setOpt.invoke(grabber, "buffer_size",         "1048576");   } catch (Throwable ignored) {}
+            try { setOpt.invoke(grabber, "probesize",           "8388608");   } catch (Throwable ignored) {}
+            try { setOpt.invoke(grabber, "analyzeduration",     "2000000");   } catch (Throwable ignored) {}
+            try { setOpt.invoke(grabber, "max_delay",           "500000");    } catch (Throwable ignored) {}
+            try { setOpt.invoke(grabber, "fflags",              "+genpts");   } catch (Throwable ignored) {}
+            try { setOpt.invoke(grabber, "user_agent",
+                "video_player/" + com.ejclaw.videoplayer.VideoPlayerMod.MOD_ID); } catch (Throwable ignored) {}
+            // Force interleaved signed 16-bit PCM so the audio sink path is single-shape.
+            try { setSampleFormat.invoke(grabber, AV_SAMPLE_FMT_S16); } catch (Throwable ignored) {}
+
+            start.invoke(grabber);
+            this.width  = (int) getW.invoke(grabber);
+            this.height = (int) getH.invoke(grabber);
+            this.ready = (width > 0 && height > 0);
+
+            int sampleRate    = safeInt(getSampleRate, grabber);
+            int audioChannels = safeInt(getAudioChannels, grabber);
+            localAudioLine = openLine(sampleRate, audioChannels);
+            this.audioLine = localAudioLine;
+
+            Class<?> frameCls    = Class.forName(FRAME_CLASS);
+            Field imageField     = frameCls.getField("image");
+            Field samplesField   = frameCls.getField("samples");
+            Class<?> convCls     = Class.forName(CONVERTER_CLASS);
+            Object converter     = convCls.getDeclaredConstructor().newInstance();
+            Method toImage       = convCls.getMethod("getBufferedImage", frameCls);
+
+            while (running.get() && !closed) {
+                if (paused.get()) { Thread.sleep(20); continue; }
+                Object frame;
+                try {
+                    frame = grab.invoke(grabber);
+                } catch (Throwable t) {
+                    // grabber.close() from another thread races our grab(); treat as a clean exit.
+                    if (!running.get() || closed) break;
+                    throw t;
+                }
+                if (frame == null) {
+                    if (loop && running.get() && !closed) {
+                        try { stop.invoke(grabber); } catch (Throwable ignored) {}
+                        try { start.invoke(grabber); } catch (Throwable ignored) {}
+                        continue;
+                    }
+                    break;
+                }
+
+                Object[] samples = (Object[]) samplesField.get(frame);
+                if (samples != null && samples.length > 0 && localAudioLine != null) {
+                    writeAudio(localAudioLine, samples, this.gain);
+                }
+
+                Object[] images = (Object[]) imageField.get(frame);
+                if (images != null && images.length > 0) {
+                    java.awt.image.BufferedImage img =
+                        (java.awt.image.BufferedImage) toImage.invoke(converter, frame);
+                    if (img != null) {
+                        ByteBuffer buf = toRgba(img);
+                        if (buf != null) latest.set(buf);
+                    }
+                }
+
+                // If we have an open audio line, SourceDataLine.write() blocks for backpressure
+                // and provides natural A/V pacing; otherwise tick ~60fps so we don't busy-loop.
+                if (localAudioLine == null) Thread.sleep(15);
+            }
+        } catch (ClassNotFoundException cnf) {
+            VideoPlayerMod.LOG.warn(
+                "[{}] JavaCV not on classpath — install org.bytedeco:javacv-platform (or javacv + ffmpeg natives)" +
+                " to enable video/audio playback. Anchor placeholder will remain visible.",
+                VideoPlayerMod.MOD_ID);
+        } catch (InterruptedException ie) {
+            Thread.currentThread().interrupt();
+        } catch (Throwable t) {
+            VideoPlayerMod.LOG.warn("[{}] JavaCV decode error: {}", VideoPlayerMod.MOD_ID, t.toString());
+        } finally {
+            ready = false;
+            this.audioLine = null;
+            if (localAudioLine != null) {
+                try { localAudioLine.stop();  } catch (Throwable ignored) {}
+                try { localAudioLine.flush(); } catch (Throwable ignored) {}
+                try { localAudioLine.close(); } catch (Throwable ignored) {}
+            }
+            this.grabberHandle = null;
+            if (grabber != null) {
+                try { grabber.getClass().getMethod("close").invoke(grabber); } catch (Throwable ignored) {}
+            }
+        }
+    }
+
+    /** Open a JavaSound output line for the stream's sample rate / channel count, or null. */
+    private static SourceDataLine openLine(int sampleRate, int channels) {
+        if (sampleRate <= 0 || channels <= 0) return null;
+        try {
+            AudioFormat fmt = new AudioFormat(sampleRate, 16, channels, true, false); // signed 16-bit LE
+            SourceDataLine line = AudioSystem.getSourceDataLine(fmt);
+            // ~0.5 s of audio buffered in the driver. Smooths over upstream hiccups without
+            // delaying close() — stopWorker() calls line.stop() / line.flush() to dump it.
+            int frameSizeBytes = 2 * channels;
+            int bufferBytes    = Math.max(sampleRate * frameSizeBytes / 2, frameSizeBytes * 1024);
+            line.open(fmt, bufferBytes);
+            line.start();
+            return line;
+        } catch (Throwable t) {
+            VideoPlayerMod.LOG.info("[{}] no audio sink ({} Hz x{}): {}",
+                VideoPlayerMod.MOD_ID, sampleRate, channels, t.toString());
+            return null;
+        }
+    }
+
+    /** Scale & write interleaved S16 PCM samples to the audio line. */
+    private static void writeAudio(SourceDataLine line, Object[] samples, float gain) {
+        if (!(samples[0] instanceof ShortBuffer sb)) return; // sample format forcing failed
+        int remaining = sb.remaining();
+        if (remaining <= 0) return;
+        byte[] pcm = new byte[remaining * 2];
+        int idx = 0;
+        if (gain >= 0.999F) {
+            while (sb.hasRemaining()) {
+                short s = sb.get();
+                pcm[idx++] = (byte) (s & 0xFF);
+                pcm[idx++] = (byte) ((s >> 8) & 0xFF);
+            }
+        } else if (gain <= 0F) {
+            // Mute: consume but emit silence so the line keeps cadence.
+            sb.position(sb.limit());
+        } else {
+            while (sb.hasRemaining()) {
+                int scaled = (int) (sb.get() * gain);
+                if (scaled >  32767) scaled =  32767;
+                if (scaled < -32768) scaled = -32768;
+                pcm[idx++] = (byte) (scaled & 0xFF);
+                pcm[idx++] = (byte) ((scaled >> 8) & 0xFF);
+            }
+        }
+        try {
+            line.write(pcm, 0, pcm.length);
+        } catch (Throwable ignored) {
+            // line may have been stop()'d from another thread mid-write — treat as a clean exit.
+        }
+    }
+
+    private static int safeInt(Method m, Object target) {
+        try { return (int) m.invoke(target); } catch (Throwable t) { return 0; }
+    }
+
+    private static ByteBuffer toRgba(java.awt.image.BufferedImage img) {
+        int w = img.getWidth(), h = img.getHeight();
+        int[] argb = img.getRGB(0, 0, w, h, null, 0, w);
+        ByteBuffer buf = ByteBuffer.allocateDirect(w * h * 4).order(ByteOrder.nativeOrder());
+        for (int p : argb) {
+            buf.put((byte) ((p >> 16) & 0xFF)); // R
+            buf.put((byte) ((p >>  8) & 0xFF)); // G
+            buf.put((byte) ( p        & 0xFF)); // B
+            buf.put((byte) ((p >> 24) & 0xFF)); // A
+        }
+        buf.flip();
+        return buf;
+    }
+}
--- a/src/main/java/com/ejclaw/videoplayer/client/playback/VideoBackend.java
+++ b/src/main/java/com/ejclaw/videoplayer/client/playback/VideoBackend.java
@@ -0,0 +1,30 @@
+package com.ejclaw.videoplayer.client.playback;
+
+import net.fabricmc.api.EnvType;
+import net.fabricmc.api.Environment;
+
+import java.nio.ByteBuffer;
+
+/**
+ * SPEC §5.3 — minimal playback backend abstraction. Implementations: WatermediaBackend (preferred,
+ * when v2 supports the target MC version) and JavaCvBackend (fallback).
+ */
+@Environment(EnvType.CLIENT)
+public interface VideoBackend {
+    void play(String url, boolean loop);
+    void pause();
+    void resume();
+    void setVolume(float gain);
+
+    boolean isReady();
+    int videoWidth();
+    int videoHeight();
+
+    /**
+     * Poll a new decoded RGBA frame if one is ready.
+     * @return the frame buffer (capacity = w*h*4) or {@code null} if no new frame is ready.
+     */
+    ByteBuffer pollFrame();
+
+    void close();
+}
--- a/src/main/java/com/ejclaw/videoplayer/client/playback/VideoCache.java
+++ b/src/main/java/com/ejclaw/videoplayer/client/playback/VideoCache.java
@@ -0,0 +1,214 @@
+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;
+import java.net.HttpURLConnection;
+import java.net.URI;
+import java.net.URLConnection;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
+import java.security.MessageDigest;
+import java.util.HashSet;
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Client-side disk cache for preloaded HTTP video URLs. Driven by the {@code /videopreload}
+ * command (routed to clients via {@code PreloadPayload}). Once a URL is fully downloaded into
+ * {@code <gameDir>/video_player_cache/<sha256>.<ext>}, {@link #lookup(String)} returns its local
+ * path so {@link VideoPlayback} can hand FFmpeg a {@code file://} input that doesn't stall on
+ * network hiccups.
+ *
+ * <p>Concurrency model: {@link #preload(String)} returns immediately and downloads on a daemon
+ * background thread. {@link #lookup(String)} only returns once the download has finished
+ * (atomic rename from {@code .part}), so callers never see a half-written file.
+ */
+@Environment(EnvType.CLIENT)
+public final class VideoCache {
+    private 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. */
+    private static final Set<String> IN_FLIGHT = ConcurrentHashMap.newKeySet();
+
+    /** Hard ceiling on a single preload — 512 MB. Keeps an accidental giant URL from filling disk. */
+    private static final long MAX_BYTES = 512L * 1024 * 1024;
+
+    /** 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)) {
+            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);
+        Thread t = new Thread(() -> download(url), "video_player-preload");
+        t.setDaemon(true);
+        t.start();
+    }
+
+    /** Return the local cached file path for this URL, or {@code null} if not yet ready. */
+    public static Path lookup(String url) {
+        if (url == null) return null;
+        Path p = READY.get(url);
+        if (p != null && Files.exists(p)) return p;
+        return null;
+    }
+
+    /** Drop the in-memory index (does not delete files). Called on disconnect. */
+    public static void clearIndex() {
+        READY.clear();
+        IN_FLIGHT.clear();
+    }
+
+    /** Caller-supplied: current set of URLs that are fully cached, for diagnostics. */
+    public static Set<String> readyUrls() {
+        return new HashSet<>(READY.keySet());
+    }
+
+    // -- internals -----------------------------------------------------------------------
+
+    private static void download(String url) {
+        Path cacheDir = cacheDir();
+        try {
+            if (cacheDir == null) {
+                VideoPlayerMod.LOG.warn("[{}] preload: no game dir, skipping {}",
+                    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");
+
+            // 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);
+                VideoPlayerMod.LOG.info("[{}] preload: indexed existing cache {} -> {}",
+                    VideoPlayerMod.MOD_ID, url, finalPath.getFileName());
+                notifyChat("[videopreload] 기존 캐시 사용: " + url, ChatFormatting.GREEN);
+                return;
+            }
+
+            URLConnection raw = URI.create(url).toURL().openConnection();
+            raw.setConnectTimeout(10_000);
+            raw.setReadTimeout(30_000);
+            raw.setRequestProperty("User-Agent", "video_player/" + VideoPlayerMod.MOD_ID);
+            if (raw instanceof HttpURLConnection http) {
+                http.setInstanceFollowRedirects(true);
+                int code = http.getResponseCode();
+                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;
+            try (InputStream in = raw.getInputStream();
+                 OutputStream out = Files.newOutputStream(partPath)) {
+                byte[] buf = new byte[64 * 1024];
+                int n;
+                while ((n = in.read(buf)) >= 0) {
+                    total += n;
+                    if (total > MAX_BYTES) {
+                        VideoPlayerMod.LOG.warn(
+                            "[{}] preload: {} exceeded {} MB cap; aborting",
+                            VideoPlayerMod.MOD_ID, url, MAX_BYTES / (1024 * 1024));
+                        try { Files.deleteIfExists(partPath); } catch (Throwable ignored) {}
+                        notifyChat("[videopreload] 실패 (512MB 초과): " + url, ChatFormatting.RED);
+                        return;
+                    }
+                    out.write(buf, 0, n);
+                }
+            }
+
+            Files.move(partPath, finalPath, StandardCopyOption.REPLACE_EXISTING,
+                StandardCopyOption.ATOMIC_MOVE);
+            READY.put(url, finalPath);
+            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,
+                ChatFormatting.RED);
+        } finally {
+            IN_FLIGHT.remove(url);
+        }
+    }
+
+    /** 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) {
+        Minecraft mc = Minecraft.getInstance();
+        if (mc == null) return;
+        mc.execute(() -> {
+            if (mc.player == null) return;
+            mc.player.sendSystemMessage(Component.literal(text).withStyle(color));
+        });
+    }
+
+    private static Path cacheDir() {
+        Minecraft mc = Minecraft.getInstance();
+        if (mc == null || mc.gameDirectory == null) return null;
+        return mc.gameDirectory.toPath().resolve("video_player_cache");
+    }
+
+    /** SHA-256 of the URL, hex. */
+    private static String sha256(String s) {
+        try {
+            MessageDigest md = MessageDigest.getInstance("SHA-256");
+            byte[] dig = md.digest(s.getBytes(java.nio.charset.StandardCharsets.UTF_8));
+            StringBuilder sb = new StringBuilder(64);
+            for (byte b : dig) sb.append(String.format("%02x", b));
+            return sb.toString();
+        } catch (Throwable t) {
+            // Fallback: tag with identity hash. Still unique within a session.
+            return "h" + Integer.toHexString(s.hashCode());
+        }
+    }
+
+    /**
+     * Best-effort filename extension from the URL path so FFmpeg's container probe gets a hint
+     * (e.g. {@code .webm} for a webm stream). Falls back to {@code .bin}.
+     */
+    private static String extensionFromUrl(String url) {
+        try {
+            String path = URI.create(url).getPath();
+            if (path == null) return ".bin";
+            int slash = path.lastIndexOf('/');
+            String tail = slash < 0 ? path : path.substring(slash + 1);
+            int dot = tail.lastIndexOf('.');
+            if (dot <= 0 || dot == tail.length() - 1) return ".bin";
+            String ext = tail.substring(dot).toLowerCase();
+            // Sanity-clamp: only allow short, safe extensions.
+            if (ext.length() > 8 || !ext.matches("\\.[a-z0-9]+")) return ".bin";
+            return ext;
+        } catch (Throwable t) {
+            return ".bin";
+        }
+    }
+}
--- a/src/main/java/com/ejclaw/videoplayer/client/playback/VideoPlayback.java
+++ b/src/main/java/com/ejclaw/videoplayer/client/playback/VideoPlayback.java
@@ -0,0 +1,219 @@
+package com.ejclaw.videoplayer.client.playback;
+
+import com.ejclaw.videoplayer.VideoPlayerMod;
+import com.ejclaw.videoplayer.block.VideoAnchorBlockEntity;
+import com.mojang.blaze3d.platform.NativeImage;
+import net.fabricmc.api.EnvType;
+import net.fabricmc.api.Environment;
+import net.minecraft.client.Minecraft;
+import net.minecraft.client.renderer.texture.DynamicTexture;
+import net.minecraft.core.BlockPos;
+import net.minecraft.resources.Identifier;
+import org.lwjgl.system.MemoryUtil;
+
+import java.nio.ByteBuffer;
+import java.nio.file.Path;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Iterator;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * SPEC §5 — per-anchor playback registry. Maps {@link BlockPos} → ({@link VideoBackend} +
+ * a {@link DynamicTexture} surface registered under a unique {@link Identifier}). The renderer
+ * reads {@link #currentTexture(BlockPos)} and binds it to the quad. {@link #tick()} pumps
+ * decoded RGBA frames into the texture.
+ *
+ * <p>When no backend is available on the classpath (e.g. JavaCV jar not installed by the
+ * user), the texture stays at its initial placeholder pattern, so the anchor's screen quad
+ * still renders as a visible surface.
+ */
+@Environment(EnvType.CLIENT)
+public final class VideoPlayback {
+    private VideoPlayback() {}
+
+    private static final int PLACEHOLDER_SIZE = 32;
+    private static final Map<BlockPos, Entry> ENTRIES = new HashMap<>();
+
+    /**
+     * Ensure a playback entry exists for this anchor and return its texture identifier.
+     * Creates a backend + dynamic texture on first call. Returns {@code null} only if the
+     * URL is empty or autoplay is off.
+     */
+    public static Identifier getOrStart(VideoAnchorBlockEntity be) {
+        BlockPos pos = be.getBlockPos();
+        Entry e = ENTRIES.get(pos);
+
+        if (be.getUrl().isEmpty() || !be.isAutoplay()) {
+            if (e != null) {
+                stop(pos);
+            }
+            return null;
+        }
+
+        if (e != null && e.url.equals(be.getUrl())) {
+            return e.id;
+        }
+        if (e != null) {
+            stop(pos);
+        }
+
+        VideoBackend backend = WatermediaProbe.isAvailable() ? new WatermediaBackend() : new JavaCvBackend();
+        // If /videopreload already cached the URL to disk, hand the local file path to FFmpeg
+        // instead of the HTTP URL — eliminates the network read entirely. Falls back to the
+        // live URL when the cache miss or the download hasn't finished yet.
+        Path cached = VideoCache.lookup(be.getUrl());
+        String source = cached != null ? cached.toAbsolutePath().toString() : be.getUrl();
+        backend.play(source, be.isLoop());
+        backend.setVolume(be.isMuted() ? 0F : be.getVolume());
+
+        Entry created = new Entry(be.getUrl(), backend);
+        ENTRIES.put(pos, created);
+        return created.id;
+    }
+
+    public static Identifier currentTexture(BlockPos pos) {
+        Entry e = ENTRIES.get(pos);
+        return e == null ? null : e.id;
+    }
+
+    public static void stop(BlockPos pos) {
+        Entry e = ENTRIES.remove(pos);
+        if (e != null) e.close();
+    }
+
+    public static void onConfigChanged(VideoAnchorBlockEntity be) {
+        if (be == null) return;
+        Entry e = ENTRIES.get(be.getBlockPos());
+        if (e == null) return;
+        if (!e.url.equals(be.getUrl())) {
+            stop(be.getBlockPos());
+            return;
+        }
+        e.backend.setVolume(be.isMuted() ? 0F : be.getVolume());
+    }
+
+    /** Called every client tick to upload new frames into the GPU texture. */
+    public static void tick() {
+        Minecraft mc = Minecraft.getInstance();
+        if (mc == null) return;
+        Iterator<Map.Entry<BlockPos, Entry>> it = ENTRIES.entrySet().iterator();
+        while (it.hasNext()) {
+            Map.Entry<BlockPos, Entry> me = it.next();
+            BlockPos pos = me.getKey();
+            Entry e = me.getValue();
+            // Belt-and-suspenders for the audio-on-delete bug: if BLOCK_ENTITY_UNLOAD didn't
+            // fire for some edge case (dimension change, chunk torn down before event runs,
+            // etc.), the BE will be gone from the level but our Entry still holds an open
+            // audio line. Catch it here and stop next tick.
+            if (mc.level == null || !(mc.level.getBlockEntity(pos) instanceof VideoAnchorBlockEntity)) {
+                e.close();
+                it.remove();
+                continue;
+            }
+            if (!e.backend.isReady()) continue;
+            ByteBuffer buf = e.backend.pollFrame();
+            if (buf == null) continue;
+            try {
+                e.upload(buf);
+            } catch (Throwable t) {
+                VideoPlayerMod.LOG.warn("[{}] texture upload failed: {}", VideoPlayerMod.MOD_ID, t.toString());
+                e.close();
+                it.remove();
+            }
+        }
+    }
+
+    public static Set<BlockPos> activePositions() {
+        return new HashSet<>(ENTRIES.keySet());
+    }
+
+    public static void setGain(BlockPos pos, float gain) {
+        Entry e = ENTRIES.get(pos);
+        if (e != null) e.backend.setVolume(gain);
+    }
+
+    public static void stopAll() {
+        for (Entry e : ENTRIES.values()) e.close();
+        ENTRIES.clear();
+    }
+
+    /** Per-anchor playback state. */
+    private static final class Entry {
+        final String url;
+        final VideoBackend backend;
+        final Identifier id;
+        DynamicTexture texture;
+        int texW = 0, texH = 0;
+        boolean registered = false;
+
+        Entry(String url, VideoBackend backend) {
+            this.url = url;
+            this.backend = backend;
+            String tag = Integer.toHexString(System.identityHashCode(this));
+            this.id = Identifier.fromNamespaceAndPath(VideoPlayerMod.MOD_ID, "dynamic/" + tag);
+            ensureTexture(PLACEHOLDER_SIZE, PLACEHOLDER_SIZE, true);
+        }
+
+        /** Allocate or resize the dynamic texture, registering it on first allocation. */
+        private void ensureTexture(int w, int h, boolean fillPlaceholder) {
+            if (texture != null && w == texW && h == texH) return;
+            if (texture != null) texture.close();
+            NativeImage img = new NativeImage(w, h, false);
+            if (fillPlaceholder) {
+                fillPlaceholder(img, w, h);
+            }
+            texture = new DynamicTexture(() -> "video_player:" + id, img);
+            texW = w;
+            texH = h;
+            Minecraft mc = Minecraft.getInstance();
+            if (mc != null) {
+                mc.getTextureManager().register(id, texture);
+                registered = true;
+            }
+            texture.upload();
+        }
+
+        /** Dark gray surface with a thin border — visible "screen" until first frame arrives. */
+        private static void fillPlaceholder(NativeImage img, int w, int h) {
+            // ABGR int. 0xAABBGGRR.
+            int body   = 0xFF202020; // dark gray
+            int border = 0xFF505050;
+            for (int y = 0; y < h; y++) {
+                for (int x = 0; x < w; x++) {
+                    boolean isEdge = (x == 0 || y == 0 || x == w - 1 || y == h - 1);
+                    img.setPixelABGR(x, y, isEdge ? border : body);
+                }
+            }
+        }
+
+        /** Copy an incoming RGBA byte buffer into the texture, resizing if dimensions changed. */
+        void upload(ByteBuffer rgba) {
+            int w = backend.videoWidth();
+            int h = backend.videoHeight();
+            if (w <= 0 || h <= 0) return;
+            ensureTexture(w, h, false);
+            NativeImage img = texture.getPixels();
+            if (img == null) return;
+
+            // RGBA bytes from the backend already match NativeImage's ABGR-int layout when
+            // viewed as little-endian bytes: byte 0 = R (low byte of ABGR int), byte 1 = G,
+            // byte 2 = B, byte 3 = A. So a flat memcpy works — no per-pixel swap needed.
+            // This replaces a 2M-iteration Java loop with one native memcpy for 1080p frames,
+            // cutting upload time from ~20ms to <1ms and removing the main stutter source.
+            long bytes = (long) w * h * 4L;
+            MemoryUtil.memCopy(MemoryUtil.memAddress(rgba), img.getPointer(), bytes);
+            texture.upload();
+        }
+
+        void close() {
+            try { backend.close(); } catch (Throwable ignored) {}
+            if (texture != null) {
+                try { texture.close(); } catch (Throwable ignored) {}
+                texture = null;
+            }
+            // texture manager keeps the registration; the texture itself is closed.
+        }
+    }
+}
--- a/src/main/java/com/ejclaw/videoplayer/client/playback/WatermediaBackend.java
+++ b/src/main/java/com/ejclaw/videoplayer/client/playback/WatermediaBackend.java
@@ -0,0 +1,50 @@
+package com.ejclaw.videoplayer.client.playback;
+
+import com.ejclaw.videoplayer.VideoPlayerMod;
+import net.fabricmc.api.EnvType;
+import net.fabricmc.api.Environment;
+
+import java.nio.ByteBuffer;
+
+/**
+ * SPEC §5.3 / §5.4 — WaterMedia v2 backend. Reflection-only so the mod jar stays clean of
+ * compile-time WaterMedia dependencies. Until a v2 build supports 1.21.6+ this returns
+ * {@code !isReady()} and {@link WatermediaProbe} reports unavailable, so callers fall through
+ * to {@link JavaCvBackend}.
+ */
+@Environment(EnvType.CLIENT)
+public class WatermediaBackend implements VideoBackend {
+    private volatile boolean ready = false;
+    private volatile int width = 0;
+    private volatile int height = 0;
+    private volatile float gain = 1.0F;
+    private Object player;
+
+    @Override
+    public void play(String url, boolean loop) {
+        if (!WatermediaProbe.isAvailable()) {
+            VideoPlayerMod.LOG.debug("[{}] WatermediaBackend.play called but probe says unavailable",
+                VideoPlayerMod.MOD_ID);
+            return;
+        }
+        // Reflection construction skipped — only reachable when WaterMedia v2 ships for the target MC.
+    }
+
+    @Override public void pause() {}
+    @Override public void resume() {}
+    @Override public void setVolume(float g) { this.gain = Math.max(0F, Math.min(1F, g)); }
+    @Override public boolean isReady() { return ready; }
+    @Override public int videoWidth()  { return width; }
+    @Override public int videoHeight() { return height; }
+
+    @Override
+    public ByteBuffer pollFrame() {
+        return null; // no frames until v2 is wired up
+    }
+
+    @Override
+    public void close() {
+        ready = false;
+        player = null;
+    }
+}
--- a/src/main/java/com/ejclaw/videoplayer/client/playback/WatermediaProbe.java
+++ b/src/main/java/com/ejclaw/videoplayer/client/playback/WatermediaProbe.java
@@ -0,0 +1,35 @@
+package com.ejclaw.videoplayer.client.playback;
+
+import com.ejclaw.videoplayer.VideoPlayerMod;
+import net.fabricmc.api.EnvType;
+import net.fabricmc.api.Environment;
+
+/**
+ * SPEC §5.4 — Reflection-only check for whether WaterMedia v2 is present and usable on this MC.
+ * As of 1.21.6+ WaterMedia v2 has no Yarn-mapped artifact, so this always reports false; we keep the
+ * shape so the mod will auto-prefer WaterMedia when a future build adds it.
+ */
+@Environment(EnvType.CLIENT)
+public final class WatermediaProbe {
+    private WatermediaProbe() {}
+
+    private static final Boolean CACHED = compute();
+
+    public static boolean isAvailable() {
+        return CACHED;
+    }
+
+    private static boolean compute() {
+        try {
+            Class.forName("me.srrapero720.watermedia.api.WaterMediaAPI", false,
+                WatermediaProbe.class.getClassLoader());
+            VideoPlayerMod.LOG.info("[{}] WaterMedia v2 detected", VideoPlayerMod.MOD_ID);
+            return true;
+        } catch (ClassNotFoundException e) {
+            return false;
+        } catch (Throwable t) {
+            VideoPlayerMod.LOG.warn("[{}] WaterMedia probe failed: {}", VideoPlayerMod.MOD_ID, t.toString());
+            return false;
+        }
+    }
+}
--- a/src/main/java/com/ejclaw/videoplayer/client/render/VideoAnchorRenderer.java
+++ b/src/main/java/com/ejclaw/videoplayer/client/render/VideoAnchorRenderer.java
@@ -0,0 +1,139 @@
+package com.ejclaw.videoplayer.client.render;
+
+import com.ejclaw.videoplayer.block.VideoAnchorBlockEntity;
+import com.ejclaw.videoplayer.client.playback.VideoPlayback;
+import com.mojang.blaze3d.vertex.PoseStack;
+import com.mojang.math.Axis;
+import net.fabricmc.api.EnvType;
+import net.fabricmc.api.Environment;
+import net.minecraft.client.renderer.SubmitNodeCollector;
+import net.minecraft.client.renderer.blockentity.BlockEntityRenderer;
+import net.minecraft.client.renderer.blockentity.BlockEntityRendererProvider;
+import net.minecraft.client.renderer.blockentity.state.BlockEntityRenderState;
+import net.minecraft.client.renderer.feature.ModelFeatureRenderer;
+import net.minecraft.client.renderer.rendertype.RenderType;
+import net.minecraft.client.renderer.rendertype.RenderTypes;
+import net.minecraft.client.renderer.state.level.CameraRenderState;
+import net.minecraft.core.Direction;
+import net.minecraft.resources.Identifier;
+import net.minecraft.world.phys.Vec3;
+import org.joml.Matrix4f;
+
+/**
+ * Draws the video as a textured quad <em>on the surface of the block the user clicked</em>.
+ *
+ * <p>The anchor BE lives in the air block adjacent to the clicked wall. Its {@code facing}
+ * field is the surface normal of the wall (= the {@link Direction} the player clicked). The
+ * quad is rotated so its normal aligns with that direction and shifted so it sits flush against
+ * the wall surface, with a tiny outward offset to avoid z-fighting.
+ */
+@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;
+
+    public VideoAnchorRenderer(BlockEntityRendererProvider.Context ctx) {
+        // no-op
+    }
+
+    @Override
+    public State createRenderState() {
+        return new State();
+    }
+
+    @Override
+    public void extractRenderState(VideoAnchorBlockEntity be, State state, float partialTick,
+                                   Vec3 cameraPos, ModelFeatureRenderer.CrumblingOverlay crumbling) {
+        BlockEntityRenderState.extractBase(be, state, crumbling);
+        state.width = be.getWidth();
+        state.height = be.getHeight();
+        state.facing = be.getFacing();
+        state.textureId = VideoPlayback.getOrStart(be);
+    }
+
+    @Override
+    public void submit(State state, PoseStack pose, SubmitNodeCollector collector, CameraRenderState camera) {
+        Identifier tex = state.textureId;
+        if (tex == null) return; // url empty or autoplay off — nothing to draw
+
+        final float w = state.width;
+        final float h = state.height;
+        final int light = state.lightCoords;
+        final Direction f = state.facing == null ? Direction.NORTH : state.facing;
+
+        pose.pushPose();
+        // 1) Move to the anchor block's center.
+        pose.translate(0.5F, 0.5F, 0.5F);
+        // 2) Rotate local +Z to align with the wall's outward normal.
+        applyFaceRotation(pose, f);
+        // 3) Place the quad's local origin (0,0) at the bottom-left corner of the anchor block's
+        //    wall face, so the clicked block becomes the lower-left and the video grows up & right.
+        //    Push it onto the wall surface (-0.5 along local +Z, the outward normal) plus a tiny
+        //    epsilon outward so the quad doesn't z-fight with the wall.
+        pose.translate(-0.5F, -0.5F, -0.5F + SURFACE_EPSILON);
+
+        final Matrix4f mat = new Matrix4f(pose.last().pose());
+        RenderType rt = RenderTypes.entityCutout(tex);
+        collector.submitCustomGeometry(pose, rt, (poseUnused, vc) -> {
+            // Front face (visible from outside, looking back at the wall)
+            emit(vc, mat, 0F, 0F, 0F, 0F, 1F, light);
+            emit(vc, mat, w,  0F, 0F, 1F, 1F, light);
+            emit(vc, mat, w,  h,  0F, 1F, 0F, light);
+            emit(vc, mat, 0F, h,  0F, 0F, 0F, light);
+            // Back face (in case the player ends up on the other side, e.g. clipping into the wall)
+            emit(vc, mat, 0F, h,  0F, 0F, 0F, light);
+            emit(vc, mat, w,  h,  0F, 1F, 0F, light);
+            emit(vc, mat, w,  0F, 0F, 1F, 1F, light);
+            emit(vc, mat, 0F, 0F, 0F, 0F, 1F, light);
+        });
+
+        pose.popPose();
+    }
+
+    /**
+     * Rotate so local +Z (the quad's outward normal in its base orientation) becomes world {@code f},
+     * with local +X mapped to the natural "right" direction the player sees when looking at the face.
+     * Derivation: for each face {@code f}, pick the rotation that maps local +Z → f, +Y → world up
+     * (or a sensible substitute for top/bottom), so the quad lies flush against the wall, oriented
+     * the way the player intuits.
+     */
+    private static void applyFaceRotation(PoseStack pose, Direction f) {
+        switch (f) {
+            case SOUTH -> { /* identity: local +Z = world +Z (south). +X = east, +Y = up. */ }
+            case NORTH -> pose.mulPose(Axis.YP.rotationDegrees(180F));  // +Z → -Z, +X → -X (west)
+            case EAST  -> pose.mulPose(Axis.YP.rotationDegrees(90F));   // +Z → +X, +X → -Z (north)
+            case WEST  -> pose.mulPose(Axis.YP.rotationDegrees(-90F));  // +Z → -X, +X → +Z (south)
+            case UP    -> pose.mulPose(Axis.XP.rotationDegrees(-90F));  // +Z → +Y, +Y → -Z (north)
+            case DOWN  -> pose.mulPose(Axis.XP.rotationDegrees(90F));   // +Z → -Y, +Y → +Z (south)
+        }
+    }
+
+    private static void emit(com.mojang.blaze3d.vertex.VertexConsumer vc, Matrix4f mat,
+                             float x, float y, float z, float u, float v, int light) {
+        vc.addVertex(mat, x, y, z)
+          .setColor(255, 255, 255, 255)
+          .setUv(u, v)
+          .setOverlay(net.minecraft.client.renderer.texture.OverlayTexture.NO_OVERLAY)
+          .setLight(light)
+          .setNormal(0F, 0F, 1F);
+    }
+
+    @Override
+    public boolean shouldRenderOffScreen() {
+        return true;
+    }
+
+    @Override
+    public int getViewDistance() {
+        return 128;
+    }
+
+    /** Per-frame render data extracted from the BE. */
+    public static final class State extends BlockEntityRenderState {
+        public Identifier textureId;
+        public int width = 1;
+        public int height = 1;
+        public Direction facing = Direction.NORTH;
+    }
+}
--- a/src/main/java/com/ejclaw/videoplayer/command/VideoDeleteCommand.java
+++ b/src/main/java/com/ejclaw/videoplayer/command/VideoDeleteCommand.java
@@ -0,0 +1,46 @@
+package com.ejclaw.videoplayer.command;
+
+import com.ejclaw.videoplayer.block.VideoAnchorBlockEntity;
+import com.mojang.brigadier.CommandDispatcher;
+import com.mojang.brigadier.exceptions.CommandSyntaxException;
+import net.minecraft.commands.CommandSourceStack;
+import net.minecraft.commands.Commands;
+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;
+
+/** SPEC §4.5.1 — {@code /videoDelete <pos>} */
+public final class VideoDeleteCommand {
+    private VideoDeleteCommand() {}
+
+    public static void register(CommandDispatcher<CommandSourceStack> dispatcher) {
+        dispatcher.register(build("videoDelete"));
+        dispatcher.register(build("videodelete"));
+    }
+
+    private static com.mojang.brigadier.builder.LiteralArgumentBuilder<CommandSourceStack>
+    build(String name) {
+        return Commands.literal(name)
+            .requires(s -> s.permissions().hasPermission(Permissions.COMMANDS_GAMEMASTER))
+            .then(Commands.argument("pos", BlockPosArgument.blockPos())
+                .executes(VideoDeleteCommand::run));
+    }
+
+    private static int run(com.mojang.brigadier.context.CommandContext<CommandSourceStack> ctx)
+            throws CommandSyntaxException {
+        CommandSourceStack src = ctx.getSource();
+        ServerLevel level = src.getLevel();
+        BlockPos pos = BlockPosArgument.getLoadedBlockPos(ctx, "pos");
+        if (!(level.getBlockEntity(pos) instanceof VideoAnchorBlockEntity)) {
+            src.sendFailure(Component.literal("no anchor at that position"));
+            return 0;
+        }
+        level.setBlock(pos, Blocks.AIR.defaultBlockState(), Block.UPDATE_ALL);
+        src.sendSuccess(() -> Component.literal("anchor deleted at " + pos.toShortString()), true);
+        return 1;
+    }
+}
--- a/src/main/java/com/ejclaw/videoplayer/command/VideoMuteCommand.java
+++ b/src/main/java/com/ejclaw/videoplayer/command/VideoMuteCommand.java
@@ -0,0 +1,62 @@
+package com.ejclaw.videoplayer.command;
+
+import com.ejclaw.videoplayer.block.VideoAnchorBlockEntity;
+import com.ejclaw.videoplayer.net.SyncAnchorPayload;
+import com.mojang.brigadier.CommandDispatcher;
+import com.mojang.brigadier.arguments.StringArgumentType;
+import com.mojang.brigadier.exceptions.CommandSyntaxException;
+import net.fabricmc.fabric.api.networking.v1.PlayerLookup;
+import net.fabricmc.fabric.api.networking.v1.ServerPlayNetworking;
+import net.minecraft.commands.CommandSourceStack;
+import net.minecraft.commands.Commands;
+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.level.ServerPlayer;
+import net.minecraft.server.permissions.Permissions;
+
+/** SPEC §4.5.1 — {@code /videoMute <pos> <on|off>} */
+public final class VideoMuteCommand {
+    private VideoMuteCommand() {}
+
+    public static void register(CommandDispatcher<CommandSourceStack> dispatcher) {
+        dispatcher.register(build("videoMute"));
+        dispatcher.register(build("videomute"));
+    }
+
+    private static com.mojang.brigadier.builder.LiteralArgumentBuilder<CommandSourceStack>
+    build(String name) {
+        return Commands.literal(name)
+            .requires(s -> s.permissions().hasPermission(Permissions.COMMANDS_GAMEMASTER))
+            .then(Commands.argument("pos", BlockPosArgument.blockPos())
+                .then(Commands.argument("state", StringArgumentType.word())
+                    .executes(VideoMuteCommand::run)));
+    }
+
+    private static int run(com.mojang.brigadier.context.CommandContext<CommandSourceStack> ctx)
+            throws CommandSyntaxException {
+        CommandSourceStack src = ctx.getSource();
+        ServerLevel level = src.getLevel();
+        BlockPos pos = BlockPosArgument.getLoadedBlockPos(ctx, "pos");
+        String state = StringArgumentType.getString(ctx, "state").toLowerCase();
+        boolean muted;
+        if ("on".equals(state) || "true".equals(state))      muted = true;
+        else if ("off".equals(state) || "false".equals(state)) muted = false;
+        else {
+            src.sendFailure(Component.literal("state must be on/off"));
+            return 0;
+        }
+        if (!(level.getBlockEntity(pos) instanceof VideoAnchorBlockEntity be)) {
+            src.sendFailure(Component.literal("no anchor at that position"));
+            return 0;
+        }
+        be.setMuted(muted);
+        for (ServerPlayer p : PlayerLookup.tracking(level, pos)) {
+            ServerPlayNetworking.send(p, new SyncAnchorPayload(pos, be.toNbt()));
+        }
+        final boolean mFinal = muted;
+        src.sendSuccess(() -> Component.literal("anchor " + (mFinal ? "muted" : "unmuted")), true);
+        return 1;
+    }
+}
--- a/src/main/java/com/ejclaw/videoplayer/command/VideoPlaceCommand.java
+++ b/src/main/java/com/ejclaw/videoplayer/command/VideoPlaceCommand.java
@@ -0,0 +1,90 @@
+package com.ejclaw.videoplayer.command;
+
+import com.ejclaw.videoplayer.block.VideoAnchorBlockEntity;
+import com.ejclaw.videoplayer.net.SyncAnchorPayload;
+import com.ejclaw.videoplayer.registry.VideoPlayerBlocks;
+import com.mojang.brigadier.CommandDispatcher;
+import com.mojang.brigadier.arguments.IntegerArgumentType;
+import com.mojang.brigadier.arguments.StringArgumentType;
+import com.mojang.brigadier.exceptions.CommandSyntaxException;
+import net.fabricmc.fabric.api.networking.v1.PlayerLookup;
+import net.fabricmc.fabric.api.networking.v1.ServerPlayNetworking;
+import net.minecraft.commands.CommandSourceStack;
+import net.minecraft.commands.Commands;
+import net.minecraft.commands.arguments.coordinates.BlockPosArgument;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Direction;
+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>} */
+public final class VideoPlaceCommand {
+    private VideoPlaceCommand() {}
+
+    public static void register(CommandDispatcher<CommandSourceStack> dispatcher) {
+        dispatcher.register(build("videoPlace"));
+        dispatcher.register(build("videoplace"));
+    }
+
+    private static com.mojang.brigadier.builder.LiteralArgumentBuilder<CommandSourceStack>
+    build(String name) {
+        return Commands.literal(name)
+            .requires(s -> s.permissions().hasPermission(Permissions.COMMANDS_GAMEMASTER))
+            .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())
+                                .executes(VideoPlaceCommand::run))))));
+    }
+
+    private static int run(com.mojang.brigadier.context.CommandContext<CommandSourceStack> ctx)
+            throws CommandSyntaxException {
+        CommandSourceStack src = ctx.getSource();
+        ServerLevel level = src.getLevel();
+        BlockPos pos = BlockPosArgument.getLoadedBlockPos(ctx, "pos");
+        Direction facing = directionFromName(StringArgumentType.getString(ctx, "facing"));
+        if (facing == null) {
+            src.sendFailure(Component.literal("facing must be north/south/east/west/up/down"));
+            return 0;
+        }
+        int width  = IntegerArgumentType.getInteger(ctx, "width");
+        int height = IntegerArgumentType.getInteger(ctx, "height");
+        String url = StringArgumentType.getString(ctx, "url").trim();
+        if (!url.isEmpty() && !(url.startsWith("http://") || url.startsWith("https://"))) {
+            src.sendFailure(Component.literal("url must be http:// or https:// (or empty)"));
+            return 0;
+        }
+        if (url.length() > 256) url = url.substring(0, 256);
+
+        level.setBlock(pos, VideoPlayerBlocks.VIDEO_ANCHOR.defaultBlockState(), Block.UPDATE_ALL);
+        if (!(level.getBlockEntity(pos) instanceof VideoAnchorBlockEntity be)) {
+            src.sendFailure(Component.literal("failed to place anchor"));
+            return 0;
+        }
+        be.setFacing(facing);
+        be.setWidth(width);
+        be.setHeight(height);
+        be.setUrl(url);
+
+        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);
+        return 1;
+    }
+
+    private static Direction directionFromName(String name) {
+        if (name == null) return null;
+        for (Direction d : Direction.values()) {
+            if (d.getSerializedName().equalsIgnoreCase(name)) return d;
+        }
+        return null;
+    }
+}
--- a/src/main/java/com/ejclaw/videoplayer/command/VideoPreloadCommand.java
+++ b/src/main/java/com/ejclaw/videoplayer/command/VideoPreloadCommand.java
@@ -0,0 +1,74 @@
+package com.ejclaw.videoplayer.command;
+
+import com.ejclaw.videoplayer.net.PreloadPayload;
+import com.mojang.brigadier.CommandDispatcher;
+import com.mojang.brigadier.arguments.StringArgumentType;
+import com.mojang.brigadier.exceptions.CommandSyntaxException;
+import net.fabricmc.fabric.api.networking.v1.PlayerLookup;
+import net.fabricmc.fabric.api.networking.v1.ServerPlayNetworking;
+import net.minecraft.commands.CommandSourceStack;
+import net.minecraft.commands.Commands;
+import net.minecraft.network.chat.Component;
+import net.minecraft.server.MinecraftServer;
+import net.minecraft.server.level.ServerPlayer;
+import net.minecraft.server.permissions.Permissions;
+
+/**
+ * {@code /videoPreload <url>} — broadcast a preload request to every connected client so each
+ * client fully downloads the URL into its local {@code video_player_cache/} folder. Subsequent
+ * {@code /videoPlace} calls (or right-click placements) that use the same URL will then play
+ * from the local file, eliminating mid-stream stutter.
+ *
+ * <p>Uses the same {@link Permissions#COMMANDS_GAMEMASTER} gate as {@code /videoPlace} et al.,
+ * so command blocks (which run at op level 2 by default) can invoke it.
+ */
+public final class VideoPreloadCommand {
+    private VideoPreloadCommand() {}
+
+    public static void register(CommandDispatcher<CommandSourceStack> dispatcher) {
+        dispatcher.register(build("videoPreload"));
+        dispatcher.register(build("videopreload"));
+    }
+
+    private static com.mojang.brigadier.builder.LiteralArgumentBuilder<CommandSourceStack>
+    build(String name) {
+        return Commands.literal(name)
+            .requires(s -> s.permissions().hasPermission(Permissions.COMMANDS_GAMEMASTER))
+            .then(Commands.argument("url", StringArgumentType.greedyString())
+                .executes(VideoPreloadCommand::run));
+    }
+
+    private static int run(com.mojang.brigadier.context.CommandContext<CommandSourceStack> ctx)
+            throws CommandSyntaxException {
+        CommandSourceStack src = ctx.getSource();
+        String url = StringArgumentType.getString(ctx, "url").trim();
+        if (url.isEmpty()) {
+            src.sendFailure(Component.literal("url is required"));
+            return 0;
+        }
+        if (!(url.startsWith("http://") || url.startsWith("https://"))) {
+            src.sendFailure(Component.literal("url must be http:// or https://"));
+            return 0;
+        }
+        if (url.length() > 256) {
+            src.sendFailure(Component.literal("url too long (max 256)"));
+            return 0;
+        }
+
+        MinecraftServer server = src.getServer();
+        PreloadPayload payload = new PreloadPayload(url);
+        int sent = 0;
+        for (ServerPlayer p : PlayerLookup.all(server)) {
+            ServerPlayNetworking.send(p, payload);
+            sent++;
+        }
+        final int sentFinal = sent;
+        // Use sendSuccess(..., false) so the chat noise is local-only and command blocks don't
+        // spam every operator on each tick. Be explicit that this is fire-and-forget: each
+        // client posts its own "[videopreload] 완료" chat line when the download finishes.
+        src.sendSuccess(() -> Component.literal(
+            "preload 요청을 " + sentFinal + " 클라이언트에 전송: " + payload.url()
+                + " (완료 알림 후 재생하세요)"), false);
+        return sent;
+    }
+}
--- a/src/main/java/com/ejclaw/videoplayer/command/VideoStickCommand.java
+++ b/src/main/java/com/ejclaw/videoplayer/command/VideoStickCommand.java
@@ -2,35 +2,35 @@ package com.ejclaw.videoplayer.command;

 import com.ejclaw.videoplayer.registry.VideoPlayerItems;
 import com.mojang.brigadier.CommandDispatcher;
-import net.minecraft.item.ItemStack;
-import net.minecraft.server.command.CommandManager;
-import net.minecraft.server.command.ServerCommandSource;
-import net.minecraft.server.network.ServerPlayerEntity;
-import net.minecraft.text.Text;
+import net.minecraft.commands.CommandSourceStack;
+import net.minecraft.commands.Commands;
+import net.minecraft.network.chat.Component;
+import net.minecraft.server.level.ServerPlayer;
+import net.minecraft.world.item.ItemStack;

 public final class VideoStickCommand {
    private VideoStickCommand() {}

-    public static void register(CommandDispatcher<ServerCommandSource> dispatcher) {
-        dispatcher.register(CommandManager.literal("videoStick")
+    public static void register(CommandDispatcher<CommandSourceStack> dispatcher) {
+        dispatcher.register(Commands.literal("videoStick")
            .executes(ctx -> run(ctx.getSource())));
        // Lowercase alias — Brigadier is case-sensitive.
-        dispatcher.register(CommandManager.literal("videostick")
+        dispatcher.register(Commands.literal("videostick")
            .executes(ctx -> run(ctx.getSource())));
    }

-    private static int run(ServerCommandSource source) {
-        ServerPlayerEntity player = source.getPlayer();
+    private static int run(CommandSourceStack source) {
+        ServerPlayer player = source.getPlayer();
        if (player == null) {
-            source.sendError(Text.literal("플레이어만 이 명령을 사용할 수 있습니다."));
+            source.sendFailure(Component.literal("플레이어만 이 명령을 사용할 수 있습니다."));
            return 0;
        }
        ItemStack stack = new ItemStack(VideoPlayerItems.VIDEO_STICK);
-        boolean inserted = player.getInventory().insertStack(stack);
+        boolean inserted = player.getInventory().add(stack);
        if (!inserted || !stack.isEmpty()) {
-            player.dropItem(stack, false);
+            player.drop(stack, false, false);
        }
-        source.sendFeedback(() -> Text.literal("비디오 스틱을 지급했습니다."), false);
+        source.sendSuccess(() -> Component.literal("비디오 스틱을 지급했습니다."), false);
        return 1;
    }
 }
--- a/src/main/java/com/ejclaw/videoplayer/item/VideoStickItem.java
+++ b/src/main/java/com/ejclaw/videoplayer/item/VideoStickItem.java
@@ -1,12 +1,71 @@
 package com.ejclaw.videoplayer.item;

-import net.minecraft.item.Item;
+import com.ejclaw.videoplayer.block.VideoAnchorBlockEntity;
+import com.ejclaw.videoplayer.net.OpenScreenPayload;
+import com.ejclaw.videoplayer.registry.VideoPlayerBlocks;
+import net.fabricmc.fabric.api.networking.v1.ServerPlayNetworking;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Direction;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.server.level.ServerPlayer;
+import net.minecraft.world.InteractionResult;
+import net.minecraft.world.entity.player.Player;
+import net.minecraft.world.item.Item;
+import net.minecraft.world.item.context.UseOnContext;
+import net.minecraft.world.level.Level;
+import net.minecraft.world.level.block.Block;
+import net.minecraft.world.level.block.state.BlockState;

 /**
- * M1: registered placeholder. Right/left-click handlers land in M4–M5.
+ * Right-click a block's face with the video stick:
+ * <ul>
+ *   <li>If a video anchor already exists in the adjacent air (= an anchor already drawn on this
+ *       face), reopen its config GUI.</li>
+ *   <li>Otherwise place an invisible anchor in the adjacent air block, set its facing to the
+ *       clicked face direction (so the renderer draws the quad flush against this face), and
+ *       open the config GUI.</li>
+ * </ul>
+ * The anchor block itself is invisible / non-collidable, so visually no new block appears —
+ * the video just shows up on the face the user clicked.
 */
 public class VideoStickItem extends Item {
-    public VideoStickItem(Settings settings) {
-        super(settings);
+    public VideoStickItem(Properties properties) {
+        super(properties);
+    }
+
+    @Override
+    public InteractionResult useOn(UseOnContext ctx) {
+        Level level = ctx.getLevel();
+        if (level.isClientSide()) {
+            return InteractionResult.SUCCESS;
+        }
+        if (!(level instanceof ServerLevel sl)) return InteractionResult.PASS;
+        Player player = ctx.getPlayer();
+        if (!(player instanceof ServerPlayer sp)) return InteractionResult.PASS;
+
+        BlockPos hit = ctx.getClickedPos();
+        Direction face = ctx.getClickedFace();
+        BlockPos anchorPos = hit.relative(face);
+
+        // Existing anchor on this face → reopen edit GUI.
+        if (sl.getBlockEntity(anchorPos) instanceof VideoAnchorBlockEntity existing) {
+            ServerPlayNetworking.send(sp, new OpenScreenPayload(anchorPos, existing.toNbt()));
+            return InteractionResult.SUCCESS;
+        }
+
+        // Need an empty / replaceable space in front of the clicked face.
+        BlockState there = sl.getBlockState(anchorPos);
+        if (!there.canBeReplaced()) return InteractionResult.PASS;
+
+        Block anchor = VideoPlayerBlocks.VIDEO_ANCHOR;
+        sl.setBlock(anchorPos, anchor.defaultBlockState(), Block.UPDATE_ALL);
+
+        if (sl.getBlockEntity(anchorPos) instanceof VideoAnchorBlockEntity be) {
+            // Surface normal of the wall we're painting on points outward in the same direction
+            // as the face the player clicked.
+            be.setFacing(face);
+            ServerPlayNetworking.send(sp, new OpenScreenPayload(anchorPos, be.toNbt()));
+        }
+        return InteractionResult.SUCCESS;
    }
 }
--- a/src/main/java/com/ejclaw/videoplayer/net/DeleteAnchorPayload.java
+++ b/src/main/java/com/ejclaw/videoplayer/net/DeleteAnchorPayload.java
@@ -0,0 +1,24 @@
+package com.ejclaw.videoplayer.net;
+
+import com.ejclaw.videoplayer.VideoPlayerMod;
+import net.minecraft.core.BlockPos;
+import net.minecraft.network.RegistryFriendlyByteBuf;
+import net.minecraft.network.codec.StreamCodec;
+import net.minecraft.network.protocol.common.custom.CustomPacketPayload;
+import net.minecraft.resources.Identifier;
+
+/** C2S — delete an anchor from the VideoConfigScreen. */
+public record DeleteAnchorPayload(BlockPos pos) implements CustomPacketPayload {
+    public static final CustomPacketPayload.Type<DeleteAnchorPayload> TYPE =
+        new CustomPacketPayload.Type<>(Identifier.fromNamespaceAndPath(VideoPlayerMod.MOD_ID, "delete_anchor"));
+
+    public static final StreamCodec<RegistryFriendlyByteBuf, DeleteAnchorPayload> CODEC = StreamCodec.composite(
+        BlockPos.STREAM_CODEC, DeleteAnchorPayload::pos,
+        DeleteAnchorPayload::new
+    );
+
+    @Override
+    public Type<? extends CustomPacketPayload> type() {
+        return TYPE;
+    }
+}
--- a/src/main/java/com/ejclaw/videoplayer/net/OpenScreenPayload.java
+++ b/src/main/java/com/ejclaw/videoplayer/net/OpenScreenPayload.java
@@ -0,0 +1,27 @@
+package com.ejclaw.videoplayer.net;
+
+import com.ejclaw.videoplayer.VideoPlayerMod;
+import net.minecraft.core.BlockPos;
+import net.minecraft.nbt.CompoundTag;
+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;
+
+/** S2C — open the VideoConfigScreen for an anchor on the client. */
+public record OpenScreenPayload(BlockPos pos, CompoundTag data) implements CustomPacketPayload {
+    public static final CustomPacketPayload.Type<OpenScreenPayload> TYPE =
+        new CustomPacketPayload.Type<>(Identifier.fromNamespaceAndPath(VideoPlayerMod.MOD_ID, "open_screen"));
+
+    public static final StreamCodec<RegistryFriendlyByteBuf, OpenScreenPayload> CODEC = StreamCodec.composite(
+        BlockPos.STREAM_CODEC, OpenScreenPayload::pos,
+        ByteBufCodecs.COMPOUND_TAG, OpenScreenPayload::data,
+        OpenScreenPayload::new
+    );
+
+    @Override
+    public Type<? extends CustomPacketPayload> type() {
+        return TYPE;
+    }
+}
--- a/src/main/java/com/ejclaw/videoplayer/net/PreloadPayload.java
+++ b/src/main/java/com/ejclaw/videoplayer/net/PreloadPayload.java
@@ -0,0 +1,27 @@
+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;
+
+/**
+ * S2C — instruct connected clients to prefetch {@code url} into their local
+ * {@code video_player_cache/} directory. Triggered by {@code /videopreload}.
+ */
+public record PreloadPayload(String url) implements CustomPacketPayload {
+    public static final CustomPacketPayload.Type<PreloadPayload> TYPE =
+        new CustomPacketPayload.Type<>(Identifier.fromNamespaceAndPath(VideoPlayerMod.MOD_ID, "preload"));
+
+    public static final StreamCodec<RegistryFriendlyByteBuf, PreloadPayload> CODEC = StreamCodec.composite(
+        ByteBufCodecs.STRING_UTF8, PreloadPayload::url,
+        PreloadPayload::new
+    );
+
+    @Override
+    public Type<? extends CustomPacketPayload> type() {
+        return TYPE;
+    }
+}
--- a/src/main/java/com/ejclaw/videoplayer/net/SaveConfigPayload.java
+++ b/src/main/java/com/ejclaw/videoplayer/net/SaveConfigPayload.java
@@ -0,0 +1,27 @@
+package com.ejclaw.videoplayer.net;
+
+import com.ejclaw.videoplayer.VideoPlayerMod;
+import net.minecraft.core.BlockPos;
+import net.minecraft.nbt.CompoundTag;
+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 — save edited config from VideoConfigScreen back to the server. */
+public record SaveConfigPayload(BlockPos pos, CompoundTag data) implements CustomPacketPayload {
+    public static final CustomPacketPayload.Type<SaveConfigPayload> TYPE =
+        new CustomPacketPayload.Type<>(Identifier.fromNamespaceAndPath(VideoPlayerMod.MOD_ID, "save_config"));
+
+    public static final StreamCodec<RegistryFriendlyByteBuf, SaveConfigPayload> CODEC = StreamCodec.composite(
+        BlockPos.STREAM_CODEC, SaveConfigPayload::pos,
+        ByteBufCodecs.COMPOUND_TAG, SaveConfigPayload::data,
+        SaveConfigPayload::new
+    );
+
+    @Override
+    public Type<? extends CustomPacketPayload> type() {
+        return TYPE;
+    }
+}
--- a/src/main/java/com/ejclaw/videoplayer/net/SyncAnchorPayload.java
+++ b/src/main/java/com/ejclaw/videoplayer/net/SyncAnchorPayload.java
@@ -0,0 +1,27 @@
+package com.ejclaw.videoplayer.net;
+
+import com.ejclaw.videoplayer.VideoPlayerMod;
+import net.minecraft.core.BlockPos;
+import net.minecraft.nbt.CompoundTag;
+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;
+
+/** S2C — push current anchor state to clients tracking the chunk. */
+public record SyncAnchorPayload(BlockPos pos, CompoundTag data) implements CustomPacketPayload {
+    public static final CustomPacketPayload.Type<SyncAnchorPayload> TYPE =
+        new CustomPacketPayload.Type<>(Identifier.fromNamespaceAndPath(VideoPlayerMod.MOD_ID, "sync_anchor"));
+
+    public static final StreamCodec<RegistryFriendlyByteBuf, SyncAnchorPayload> CODEC = StreamCodec.composite(
+        BlockPos.STREAM_CODEC, SyncAnchorPayload::pos,
+        ByteBufCodecs.COMPOUND_TAG, SyncAnchorPayload::data,
+        SyncAnchorPayload::new
+    );
+
+    @Override
+    public Type<? extends CustomPacketPayload> type() {
+        return TYPE;
+    }
+}
--- a/src/main/java/com/ejclaw/videoplayer/net/VideoPlayerNetwork.java
+++ b/src/main/java/com/ejclaw/videoplayer/net/VideoPlayerNetwork.java
@@ -0,0 +1,110 @@
+package com.ejclaw.videoplayer.net;
+
+import com.ejclaw.videoplayer.VideoPlayerMod;
+import com.ejclaw.videoplayer.block.VideoAnchorBlockEntity;
+import net.fabricmc.fabric.api.networking.v1.PayloadTypeRegistry;
+import net.fabricmc.fabric.api.networking.v1.PlayerLookup;
+import net.fabricmc.fabric.api.networking.v1.ServerPlayNetworking;
+import net.minecraft.core.BlockPos;
+import net.minecraft.nbt.CompoundTag;
+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;
+import net.minecraft.world.level.block.Blocks;
+
+/**
+ * Registers all four payload types and the two C2S server-side receivers.
+ * Client-side receivers are registered in {@code com.ejclaw.videoplayer.client.net.ClientNetworking}.
+ */
+public final class VideoPlayerNetwork {
+    private VideoPlayerNetwork() {}
+
+    public static void registerPayloadTypes() {
+        // S2C
+        PayloadTypeRegistry.clientboundPlay().register(OpenScreenPayload.TYPE, OpenScreenPayload.CODEC);
+        PayloadTypeRegistry.clientboundPlay().register(SyncAnchorPayload.TYPE, SyncAnchorPayload.CODEC);
+        PayloadTypeRegistry.clientboundPlay().register(PreloadPayload.TYPE, PreloadPayload.CODEC);
+        // C2S
+        PayloadTypeRegistry.serverboundPlay().register(SaveConfigPayload.TYPE, SaveConfigPayload.CODEC);
+        PayloadTypeRegistry.serverboundPlay().register(DeleteAnchorPayload.TYPE, DeleteAnchorPayload.CODEC);
+    }
+
+    public static void registerServerReceivers() {
+        ServerPlayNetworking.registerGlobalReceiver(SaveConfigPayload.TYPE, (payload, context) -> {
+            ServerPlayer player = context.player();
+            ServerLevel level = player.level();
+            BlockPos pos = payload.pos();
+            CompoundTag data = payload.data();
+            context.server().execute(() -> handleSave(level, player, pos, data));
+        });
+
+        ServerPlayNetworking.registerGlobalReceiver(DeleteAnchorPayload.TYPE, (payload, context) -> {
+            ServerPlayer player = context.player();
+            ServerLevel level = player.level();
+            BlockPos pos = payload.pos();
+            context.server().execute(() -> handleDelete(level, player, pos));
+        });
+    }
+
+    private static void handleSave(ServerLevel level, ServerPlayer player, BlockPos pos, CompoundTag data) {
+        if (!canModify(player, pos)) {
+            VideoPlayerMod.LOG.warn("[{}] {} attempted save without permission at {}",
+                VideoPlayerMod.MOD_ID, player.getName().getString(), pos);
+            return;
+        }
+        if (!(level.getBlockEntity(pos) instanceof VideoAnchorBlockEntity be)) {
+            return;
+        }
+        be.applyFromNbt(sanitize(data));
+        // broadcast updated state to all players tracking the chunk
+        SyncAnchorPayload sync = new SyncAnchorPayload(pos, be.toNbt());
+        for (ServerPlayer watcher : PlayerLookup.tracking(level, pos)) {
+            ServerPlayNetworking.send(watcher, sync);
+        }
+    }
+
+    private static void handleDelete(ServerLevel level, ServerPlayer player, BlockPos pos) {
+        if (!canModify(player, pos)) {
+            return;
+        }
+        if (level.getBlockEntity(pos) instanceof VideoAnchorBlockEntity) {
+            level.setBlock(pos, Blocks.AIR.defaultBlockState(), Block.UPDATE_ALL);
+        }
+    }
+
+    /** Permission check: creative players or operators may modify anchors. */
+    public static boolean canModify(ServerPlayer player, BlockPos pos) {
+        if (player.isCreative()) return true;
+        return player.permissions().hasPermission(Permissions.COMMANDS_GAMEMASTER);
+    }
+
+    /** Strip out unexpected keys from C2S NBT before applying. */
+    private static CompoundTag sanitize(CompoundTag in) {
+        CompoundTag out = new CompoundTag();
+        out.putString("url", trimUrl(in.getStringOr("url", "")));
+        out.putInt("width", clamp(in.getIntOr("width", 1), 1, 32));
+        out.putInt("height", clamp(in.getIntOr("height", 1), 1, 32));
+        out.putString("facing", in.getStringOr("facing", "north"));
+        out.putBoolean("loop", in.getBooleanOr("loop", true));
+        out.putFloat("volume", Math.max(0F, Math.min(1F, in.getFloatOr("volume", 0.5F))));
+        out.putBoolean("muted", in.getBooleanOr("muted", false));
+        out.putBoolean("autoplay", in.getBooleanOr("autoplay", true));
+        return out;
+    }
+
+    private static String trimUrl(String s) {
+        if (s == null) return "";
+        String t = s.trim();
+        if (t.length() > 256) t = t.substring(0, 256);
+        // SPEC §4.4: only https?:// or empty
+        if (!t.isEmpty() && !(t.startsWith("http://") || t.startsWith("https://"))) {
+            return "";
+        }
+        return t;
+    }
+
+    private static int clamp(int v, int lo, int hi) {
+        return Math.max(lo, Math.min(hi, v));
+    }
+}
--- a/src/main/java/com/ejclaw/videoplayer/registry/VideoPlayerBlockEntities.java
+++ b/src/main/java/com/ejclaw/videoplayer/registry/VideoPlayerBlockEntities.java
@@ -3,17 +3,17 @@ package com.ejclaw.videoplayer.registry;
 import com.ejclaw.videoplayer.VideoPlayerMod;
 import com.ejclaw.videoplayer.block.VideoAnchorBlockEntity;
 import net.fabricmc.fabric.api.object.builder.v1.block.entity.FabricBlockEntityTypeBuilder;
-import net.minecraft.block.entity.BlockEntityType;
-import net.minecraft.registry.Registries;
-import net.minecraft.registry.Registry;
-import net.minecraft.util.Identifier;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.core.Registry;
+import net.minecraft.resources.Identifier;
+import net.minecraft.world.level.block.entity.BlockEntityType;

 public final class VideoPlayerBlockEntities {
    private VideoPlayerBlockEntities() {}

    public static final BlockEntityType<VideoAnchorBlockEntity> VIDEO_ANCHOR = Registry.register(
-        Registries.BLOCK_ENTITY_TYPE,
-        Identifier.of(VideoPlayerMod.MOD_ID, "video_anchor"),
+        BuiltInRegistries.BLOCK_ENTITY_TYPE,
+        Identifier.fromNamespaceAndPath(VideoPlayerMod.MOD_ID, "video_anchor"),
        FabricBlockEntityTypeBuilder.create(VideoAnchorBlockEntity::new, VideoPlayerBlocks.VIDEO_ANCHOR).build()
    );

--- a/src/main/java/com/ejclaw/videoplayer/registry/VideoPlayerBlocks.java
+++ b/src/main/java/com/ejclaw/videoplayer/registry/VideoPlayerBlocks.java
@@ -2,20 +2,24 @@ package com.ejclaw.videoplayer.registry;

 import com.ejclaw.videoplayer.VideoPlayerMod;
 import com.ejclaw.videoplayer.block.VideoAnchorBlock;
-import net.minecraft.block.AbstractBlock;
-import net.minecraft.block.Block;
-import net.minecraft.registry.Registries;
-import net.minecraft.registry.Registry;
-import net.minecraft.registry.RegistryKey;
-import net.minecraft.registry.RegistryKeys;
-import net.minecraft.util.Identifier;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.core.Registry;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.world.level.block.Block;
+import net.minecraft.world.level.block.state.BlockBehaviour;

 public final class VideoPlayerBlocks {
    private VideoPlayerBlocks() {}

    public static final Block VIDEO_ANCHOR = register(
        "video_anchor",
-        AbstractBlock.Settings.create().strength(1.0F).nonOpaque(),
+        BlockBehaviour.Properties.of()
+            .noCollision()
+            .noOcclusion()
+            .instabreak()
+            .replaceable()
+            .strength(0F),
        VideoAnchorBlock::new
    );

@@ -25,13 +29,13 @@ public final class VideoPlayerBlocks {

    @FunctionalInterface
    private interface BlockFactory<B extends Block> {
-        B create(AbstractBlock.Settings settings);
+        B create(BlockBehaviour.Properties properties);
    }

-    private static <B extends Block> B register(String name, AbstractBlock.Settings settings, BlockFactory<B> factory) {
-        Identifier id = Identifier.of(VideoPlayerMod.MOD_ID, name);
-        RegistryKey<Block> key = RegistryKey.of(RegistryKeys.BLOCK, id);
-        B block = factory.create(settings.registryKey(key));
-        return Registry.register(Registries.BLOCK, key, block);
+    private static <B extends Block> B register(String name, BlockBehaviour.Properties props, BlockFactory<B> factory) {
+        Identifier id = Identifier.fromNamespaceAndPath(VideoPlayerMod.MOD_ID, name);
+        ResourceKey<Block> key = ResourceKey.create(BuiltInRegistries.BLOCK.key(), id);
+        B block = factory.create(props.setId(key));
+        return Registry.register(BuiltInRegistries.BLOCK, key, block);
    }
 }
--- a/src/main/java/com/ejclaw/videoplayer/registry/VideoPlayerItems.java
+++ b/src/main/java/com/ejclaw/videoplayer/registry/VideoPlayerItems.java
@@ -2,34 +2,33 @@ package com.ejclaw.videoplayer.registry;

 import com.ejclaw.videoplayer.VideoPlayerMod;
 import com.ejclaw.videoplayer.item.VideoStickItem;
-import net.minecraft.item.Item;
-import net.minecraft.registry.Registries;
-import net.minecraft.registry.Registry;
-import net.minecraft.registry.RegistryKey;
-import net.minecraft.registry.RegistryKeys;
-import net.minecraft.util.Identifier;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.core.Registry;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.world.item.Item;

 public final class VideoPlayerItems {
    private VideoPlayerItems() {}

    public static final Item VIDEO_STICK = register(
        "video_stick",
-        settings -> new VideoStickItem(settings.maxCount(1))
+        props -> new VideoStickItem(props.stacksTo(1))
    );

    public static void register() {
-        // For M1 we don't add to a vanilla item group; players get the stick via /videoStick.
+        // players get the stick via /videoStick command
    }

    @FunctionalInterface
    private interface ItemFactory<I extends Item> {
-        I create(Item.Settings settings);
+        I create(Item.Properties properties);
    }

    private static <I extends Item> I register(String name, ItemFactory<I> factory) {
-        Identifier id = Identifier.of(VideoPlayerMod.MOD_ID, name);
-        RegistryKey<Item> key = RegistryKey.of(RegistryKeys.ITEM, id);
-        I item = factory.create(new Item.Settings().registryKey(key));
-        return Registry.register(Registries.ITEM, key, item);
+        Identifier id = Identifier.fromNamespaceAndPath(VideoPlayerMod.MOD_ID, name);
+        ResourceKey<Item> key = ResourceKey.create(BuiltInRegistries.ITEM.key(), id);
+        I item = factory.create(new Item.Properties().setId(key));
+        return Registry.register(BuiltInRegistries.ITEM, key, item);
    }
 }
--- a/src/main/resources/assets/video_player/blockstates/video_anchor.json
+++ b/src/main/resources/assets/video_player/blockstates/video_anchor.json
@@ -0,0 +1,5 @@
+{
+  "variants": {
+    "": { "model": "video_player:block/video_anchor" }
+  }
+}
--- a/src/main/resources/assets/video_player/items/video_stick.json
+++ b/src/main/resources/assets/video_player/items/video_stick.json
@@ -0,0 +1,6 @@
+{
+  "model": {
+    "type": "minecraft:model",
+    "model": "video_player:item/video_stick"
+  }
+}
--- a/src/main/resources/assets/video_player/models/block/video_anchor.json
+++ b/src/main/resources/assets/video_player/models/block/video_anchor.json
@@ -0,0 +1,5 @@
+{
+  "textures": {
+    "particle": "video_player:block/video_anchor"
+  }
+}
--- a/src/main/resources/assets/video_player/models/item/video_stick.json
+++ b/src/main/resources/assets/video_player/models/item/video_stick.json
@@ -0,0 +1,6 @@
+{
+  "parent": "minecraft:item/generated",
+  "textures": {
+    "layer0": "video_player:item/video_stick"
+  }
+}
--- a/src/main/resources/assets/video_player/textures/block/video_anchor.png
+++ b/src/main/resources/assets/video_player/textures/block/video_anchor.png
--- a/src/main/resources/assets/video_player/textures/item/video_stick.png
+++ b/src/main/resources/assets/video_player/textures/item/video_stick.png
--- a/src/main/resources/fabric.mod.json
+++ b/src/main/resources/fabric.mod.json
@@ -16,9 +16,9 @@
    "client": [ "com.ejclaw.videoplayer.VideoPlayerClient" ]
  },
  "depends": {
-    "fabricloader": ">=0.16.0",
+    "fabricloader": ">=0.19.0",
    "fabric-api": "*",
-    "minecraft": ">=1.21.6",
-    "java": ">=21"
+    "minecraft": "${target_minecraft}",
+    "java": ">=25"
  }
 }
Author	SHA1	Message	Date
tkrmagid	7b7fd7f320	v0.4.7: smoother playback via memcpy upload + render-rate pump Some checks failed build / build (push) Has been cancelled Details - Replace per-pixel RGBA->ABGR loop in Entry.upload() with a single MemoryUtil.memCopy() into NativeImage's native buffer. The two layouts are identical when viewed as little-endian bytes, so no swap is needed. Cuts 1080p upload time from a ~2M-iter Java loop to one native memcpy. - Move the frame-pump tick from 20Hz client tick (END_CLIENT_TICK) to per-render-frame (LevelRenderEvents.START_MAIN). At 60+fps display vs 24fps source, this removes the worst stutter window where a decoded frame waited up to 50ms for the next tick. Distance-gain math stays on 20Hz where it's plenty. - Bump version 0.4.6 -> 0.4.7 in gradle.properties and README.	2026-05-15 22:06:15 +09:00
tkrmagid	d34dc97671	v0.4.6: server config for auto-preload on join Some checks failed build / build (push) Has been cancelled Details - new: config/video_player.json on first server start. Field preload_urls is a list of HTTP(S) URLs (≤256 chars each) that the server broadcasts via PreloadPayload to every player when they finish joining, so common videos are warmed into each client's video_player_cache/ before they ever play. Reuses the same PreloadPayload + VideoCache path as /videopreload, so chat feedback ("[videopreload] 완료") still applies. - config is loaded once at mod init; invalid entries are dropped with a WARN line. Edit + restart server to apply changes.	2026-05-15 21:58:26 +09:00
tkrmagid	e6faae3f39	v0.4.5: panel-center audio, preload chat feedback, defensive BE check Some checks failed build / build (push) Has been cancelled Details - audio: distance attenuation now uses the panel center (width/2, height/2 offset from the anchor along the renderer's right/up axes) instead of the anchor block corner, so a 4x4 panel sounds like it's coming from the middle of the screen and not the bottom-left. - preload: each client now posts a chat line on start / completion / failure / cache-hit, so a command-block sequence like /videopreload -> /videoplace can be timed against the visible "[videopreload] 완료" message. - safety: VideoPlayback.tick() verifies the anchor BE still exists at each active position and forcibly stops playback if it doesn't — covers any edge case where BLOCK_ENTITY_UNLOAD doesn't fire. - /videopreload feedback now explicitly states "완료 알림 후 재생하세요".	2026-05-15 21:53:21 +09:00
tkrmagid	4fc7cf46b7	v0.4.4: fix audio-on-delete, reduce stutter, add /videopreload Some checks failed build / build (push) Has been cancelled Details - fix: stop playback when anchor block entity unloads (BLOCK_ENTITY_UNLOAD) so deleting a video while audio is playing actually silences it. - fix: force-stop SourceDataLine and grabber from outside the worker thread so a blocked line.write() / grab() unblocks immediately on close. - perf: tune FFmpeg streaming options (buffer_size, probesize, analyzeduration, max_delay, fflags=+genpts, reconnect_delay_max) and pre-size audio line buffer to ~0.5s to smooth out mid-stream stutter. - feat: /videopreload <url> broadcasts a S2C PreloadPayload to all clients; each client downloads the URL to <gameDir>/video_player_cache/<sha256> and subsequent playback reads from the local file instead of streaming. Gated by COMMANDS_GAMEMASTER (op level 2), so command blocks can invoke it.	2026-05-15 21:42:11 +09:00
tkrmagid	0d1f802555	docs: add missing javacpp native jar to install guide (v0.4.3) Some checks failed build / build (push) Has been cancelled Details JavaCPP Loader (javacpp.jar) ships pure-Java code that needs its own JNI bridge DLL (jnijavacpp) to extract & link other native libraries. That bridge lives in the platform-specific javacpp-<os>-<arch>.jar which the old install guide silently omitted — users following it ended up with a black panel and an UnsatisfiedLinkError for jnijavacpp because FFmpeg natives could never be loaded. This bumps the required JavaCV jar list from 4 to 5, updates the -Xbootclasspath/a: examples on all three OSes, and adds a diagnostic note for the matching log line. Docs-only change; mod code is unchanged from v0.4.2.	2026-05-15 21:22:02 +09:00
tkrmagid	8f11fe24bf	docs: bump README to v0.4.2, note 0.4.1 stick-icon defect Some checks failed build / build (push) Has been cancelled Details Reviewer caught that the README still pointed users at video_player-0.4.1.jar even though 0.4.2 fixes the stick missing-model issue. Updated: - "current version" header → 0.4.2 - STEP 4 download filename → video_player-0.4.2.jar - build output path → build/libs/video_player-0.4.2.jar - STEP 6 verification: explicitly call out that 0.4.1 and below have a known stick-icon defect (unprefixed item/generated parent rejected by the 26.1.2 model loader) so users on those versions need to upgrade, not just dedupe. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-15 21:04:49 +09:00
tkrmagid	4b14fb479b	fix(item): namespace item/generated parent for 26.1.2 model loader (v0.4.2) Some checks failed build / build (push) Has been cancelled Details The held video_stick item rendered as the default missing-model cube even with v0.4.1 jar loaded (lang strings resolved, so the mod itself was active). Root cause confirmed against Fabric 26.1.2 docs: the new model loader no longer auto-resolves unprefixed parent paths. `item/generated` needs to be written as `minecraft:item/generated`. models/item/video_stick.json — parent → minecraft:item/generated. gradle.properties — 0.4.1 → 0.4.2. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-15 21:02:03 +09:00
tkrmagid	693c1f2cd1	docs: require absolute paths in JVM args, drop %APPDATA% expansion myth Some checks failed build / build (push) Has been cancelled Details User followed README using %APPDATA% in -Xbootclasspath/a: and the official Mojang launcher passed the literal string through to Java without expanding it, so boot classpath ended up empty and video stayed black despite all 4 JavaCV jars being present. Replaced the %APPDATA% example with an absolute C:\Users\<name>\AppData\ Roaming\... template, added a callout warning that the launcher does not expand env vars in JVM args, and pointed at `echo %APPDATA%` from cmd as the way to discover the right path. Also corrected the ffmpeg jar filenames: the bundle zip uses the short form (e.g. ffmpeg-windows-x86_64.jar), not the Maven-style ffmpeg-8.0.1-1.5.13-windows-x86_64.jar. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-15 20:58:46 +09:00
tkrmagid	137767e75c	docs: pin direct Fabric API 26.1.2 download link, warn about version suffix Some checks failed build / build (push) Has been cancelled Details User reported Incompatible-mods crash because they downloaded fabric-api-0.140.2+1.21.11.jar from Modrinth (Modrinth's version-filter URL param does not always restrict the listing to the requested game version). Replaced the generic search-page link with the direct CDN URL of fabric-api-0.149.0+26.1.2.jar and added a callout telling readers to verify the filename suffix ends in +26.1.2.jar. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-15 20:55:32 +09:00
tkrmagid	6e2ef661ea	docs: rewrite README for first-time users on official launcher + Fabric Some checks failed build / build (push) Has been cancelled Details Previous README used "방법 A/B/C" terminology that confused readers and recommended Prism over the official launcher. Per user feedback, restructured into a step-by-step guide assuming the official Mojang launcher: 1. boot 26.1.2 vanilla once to create .minecraft 2. run fabric-installer-1.x for client / 26.1.2 / loader 0.19.2 3. open .minecraft/mods (per-OS instructions) 4. drop fabric-api + video_player-0.4.1.jar, remove old versions 5. install JavaCV — two routes: 5-A. Prism Launcher (easiest) 5-B. official launcher via -Xbootclasspath/a: with Windows/macOS/Linux examples 6. verify with /videostick Moved Maven coords to a developer footnote. Added install verification step to disambiguate "missing texture" symptom from leftover old-version jars. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-15 20:44:47 +09:00
tkrmagid	d382babfbd	docs: client-side install guide for v0.4.1 + JavaCV 1.5.13 Some checks failed build / build (push) Has been cancelled Details README rewritten for MC 26.1.2 / Java 25 / Fabric Loader 0.19.2 target. Added JavaCV install section (Prism/MultiMC preferred, JVM args fallback, Maven coords for builders) pointing at the 2026-02-22 1.5.13 binaries bundling FFmpeg 8.0.1. Usage section reflects the v0.4.1 invisible-anchor flow: clicked block = bottom-left, sneak+left-click deletes. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-15 20:39:02 +09:00
tkrmagid	459b3249a4	fix(render): anchor video to clicked block's bottom-left, EAST/WEST flush Some checks failed build / build (push) Has been cancelled Details Three fixes for v0.4.1: 1. Video stick item rendered as missing-texture because 26.1.2 requires the new client_item descriptor at assets/<mod>/items/<name>.json. Add it; the existing models/item/video_stick.json is kept as the underlying model. 2. Quad placement now anchors the local (0,0) corner at the bottom-left of the wall face the player clicked, so the clicked block is the BL and the video grows up & right. Previously it was centered on the anchor. 3. EAST/WEST face rotations were swapped, which placed the quad on the far side of the air block (~1 block away from the wall) instead of flush. Derived the correct rotations from first principles: EAST = Axis.YP +90° (local +Z → world +X, +X → -Z = north) WEST = Axis.YP -90° (local +Z → world -X, +X → +Z = south) NORTH/SOUTH/UP/DOWN math re-verified — those were already correct.	2026-05-15 20:21:19 +09:00
tkrmagid	2b50f56980	render: paint video on the clicked wall face (no visible anchor block) Some checks failed build / build (push) Has been cancelled Details The anchor block becomes invisible and non-collidable; it exists only as a BlockEntity host in the air block adjacent to the clicked wall. The renderer now translates and rotates the textured quad so it sits flush against the surface of the wall the user actually clicked, on any of the six faces. Stick interaction: right-click face → place anchor at hit.relative(face), facing=face, open GUI right-click face with anchor already there → reopen the GUI sneak + left-click face with stick → delete the anchor on that face The anchor's selection outline / collision / occlusion are all empty, so the player can target the wall block behind it without interference. JavaCV / streaming polish: - Bump missing-JavaCV log to WARN so users notice when the runtime jar is not installed (previously buried at INFO). - Add HTTP resilience options: `timeout`, `reconnect`, `reconnect_streamed`, `reconnect_at_eof`, and a `user_agent` so picky servers don't 403 us.	2026-05-15 20:08:33 +09:00
tkrmagid	429244d820	audio: route JavaCV samples through SourceDataLine with live gain Some checks failed build / build (push) Has been cancelled Details setVolume/Mute previously stored gain without affecting audible output: the backend only called grabImage() and never opened an audio sink. Switch to grab() (interleaved video+audio frames), force AV_SAMPLE_FMT_S16 on the grabber so samples are always interleaved signed 16-bit PCM, open a matching JavaSound SourceDataLine and write scaled samples per-frame. gain is read on every block so /videoMute, GUI Mute and the per-tick distance attenuation now take effect immediately. SourceDataLine.write blocking provides natural A/V pacing, so the legacy 15ms sleep is dropped when an audio line is open; sleep is retained as a 60fps cap when there is no audio device. bump version to 0.3.1.	2026-05-15 19:45:42 +09:00
tkrmagid	52fbcd1861	render: restore textured quad on new 26.1.2 BlockEntityRenderer pipeline Some checks failed build / build (push) Has been cancelled Details VideoPlayback now allocates a DynamicTexture per active anchor under a unique Identifier (registered on Minecraft.getTextureManager()) and pumps RGBA frames into it via NativeImage.setPixelABGR + DynamicTexture.upload() during the client tick. Until the backend (JavaCV) produces a first frame, the texture shows a dark gray placeholder with a thin border so the anchor screen is visibly present. VideoAnchorRenderer.submit() now uses SubmitNodeCollector.submitCustomGeometry with RenderTypes.entityCutout(textureId), drawing a two-sided width×height quad oriented by Direction.toYRot() + Axis.YP.rotationDegrees. Vertex attributes use the new VertexConsumer fluent API (addVertex(Matrix4f, ...) .setColor.setUv.setOverlay(NO_OVERLAY).setLight.setNormal). JavaCvBackend / WatermediaBackend / WatermediaProbe / VideoBackend are unchanged — JavaCV is referenced entirely via reflection so the mod jar remains loadable when the bytedeco classifier jars aren't on the runtime classpath, in which case the anchor renders its placeholder surface.	2026-05-15 19:38:23 +09:00
tkrmagid	27a3f34bfa	port: migrate all sources from Yarn 1.21.x to Mojmap 26.1.2 Some checks failed build / build (push) Has been cancelled Details - Block/BE/Item: BaseEntityBlock + useItemOn(InteractionResult), useOn(UseOnContext), setChanged(), loadAdditional(ValueInput) / saveAdditional(ValueOutput) with getStringOr/getIntOr/getBooleanOr/getFloatOr defaults - Registries: BuiltInRegistries + ResourceKey + Properties.setId(ResourceKey) - Networking: CustomPacketPayload.Type + StreamCodec.composite + RegistryFriendlyByteBuf (note: clientboundPlay/serverboundPlay names in fabric-networking-api-v1 6.3.1) - Commands: Commands.literal/argument, CommandSourceStack.sendSuccess/sendFailure, PermissionSet.hasPermission(Permissions.COMMANDS_GAMEMASTER) (level-2 equivalent) - Client GUI: EditBox / Button / Checkbox / AbstractSliderButton + addRenderableWidget (no render override; widgets render themselves under the new pipeline) - Renderer: rewritten as stub against new BlockEntityRenderer<T, S extends BlockEntityRenderState> pattern (createRenderState / extractRenderState / submit). Stub does not draw a quad yet — frame upload and dynamic texture surface deferred until Watermedia/JavaCV are re-audited for Java 25 - Playback: stripped to bookkeeping-only stub (tracks active anchors, no frame pump) - Client entrypoint: ClientTickEvents.END_LEVEL_TICK (was END_WORLD_TICK), Minecraft.level, LocalPlayer, Vec3, InteractionResult ./gradlew build passes against MC 26.1.2 + Fabric Loader 0.19.2 + fabric-api 0.149.0+26.1.2. Block placement, anchor BE, payloads, commands, and GUI are functional; the anchor renders as the plain block until the new render-state pipeline is wired with a texture.	2026-05-15 19:27:12 +09:00
tkrmagid	8f69814cb2	build: switch toolchain to MC 26.1.2 (intermediary retired) Some checks failed build / build (push) Has been cancelled Details - net.fabricmc.fabric-loom 1.16-SNAPSHOT (no remap; MC 26.1+ ships unobfuscated) - gradle.properties: minecraft_version=26.1.2, loader=0.19.2, fabric-api=0.149.0+26.1.2 - Java 25 toolchain - fabric.mod.json: fabricloader>=0.19.0, java>=25 - Drop multi-version build script + matrix CI (single-target now) - Backup of 1.21.6/7/8 working tree preserved on mc-1.21.x branch Source migration to Mojmap names is in progress on follow-up commits; this commit alone will not build until source files are ported. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-15 19:09:59 +09:00
tkrmagid	ddc16f3d90	M2-M8: renderer, playback backends, GUI/network, commands, multi-version build Some checks failed build-matrix / build (0.120.1+1.21.6, 1.21.6, 1.21.6+build.1) (push) Has been cancelled Details build-matrix / build (0.129.0+1.21.7, 1.21.7, 1.21.7+build.8) (push) Has been cancelled Details build-matrix / build (0.136.1+1.21.8, 1.21.8, 1.21.8+build.1) (push) Has been cancelled Details - M2: VideoAnchorRenderer draws width\u00d7height quad oriented by facing - M3: VideoBackend interface + JavaCV (reflection) and WaterMedia (probe) backends - M4: VideoConfigScreen GUI + 4 typed payloads + NBT persistence via ReadView/WriteView - M5: stick item useOnBlock place/edit, AttackBlockCallback delete, /videoPlace /videoDelete /videoMute - M6: per-tick distance attenuation gain = volume * clamp(1 - d/16, 0, 1), mute zeroes gain - M7: WatermediaProbe (reflection-only; reports unavailable until v2 supports 1.21.6+) - M8: multi-version build script (1.21.6/1.21.7/1.21.8) + Gitea Actions matrix workflow	2026-05-15 10:45:28 +09:00