v0.4.9: kill BufferedImage path, release texture on close

Stutter fix (root cause):
- 0.4.7 made the GPU upload a memcpy, but toRgba() in JavaCvBackend was
  still doing BufferedImage.getRGB() + a per-pixel ARGB->RGBA loop. That
  loop ran 20-50ms per 1080p frame on the decode thread. When it slipped
  behind real-time, the audio buffer drained, backpressure vanished,
  the decoder burst-fired catch-up frames into the single-slot
  AtomicReference (dropping 11 of 12 for ~0.5s of buffer), then blocked
  again on the next audio refill -- exactly the periodic stutter the
  user reported.
- Force the grabber to output AV_PIX_FMT_RGBA (=26) via setPixelFormat.
  Now frame.image[0] is already a ByteBuffer of RGBA bytes; we just
  copy it into a fresh direct buffer and hand it to the upload path.
  The colorspace conversion happens inside swscale (native SIMD) at
  <1ms per frame, so the decoder consistently keeps real-time pace and
  the audio backpressure stays smooth.
- Removed Java2DFrameConverter / BufferedImage usage entirely.

Defensive delete fix (potential crash on anchor delete):
- Entry.close() now calls TextureManager.release(id) before closing the
  texture itself. Without this, a RenderType cached by Identifier could
  still try to bind the dead GL handle on the next frame and crash the
  render thread. The crash report the user reported couldn't be located
  (no crash-reports/ folder) so this is the most plausible suspect from
  reading the code; full diagnosis still pending the tail of latest.log.

README.md

@@ -3,7 +3,7 @@
 마인크래프트 안에서 임의의 동영상 URL을 벽·바닥·천장에 평면으로 재생하는 Fabric 모드.
 
 - 모드 ID: `video_player`
-- 현재 버전: **0.4.3**
+- 현재 버전: **0.4.9**
 - 마인크래프트 버전: **26.1.2**
 - 필요 Java: **25** (마인크래프트 26.x 가 요구함)
 
@@ -51,91 +51,23 @@ Fabric은 마인크래프트에 모드 기능을 추가해 주는 로더입니
      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** (이 모드)
+2. **video_player** (이 모드, 0.4.9 부터 JavaCV 가 jar 안에 포함됨)
    - 다운로드: https://git.tkrmagid.kr/tkrmagid/mc_video_player_mod/releases
-   - `video_player-0.4.3.jar` 를 다운로드해서 같은 `mods` 폴더에 넣습니다.
+   - 자신의 OS·CPU 에 맞는 jar **한 개** 만 받아서 `mods` 폴더에 넣으면 됩니다 (별도 JavaCV 설치 불필요):
+     - Windows 64bit: `video_player-windows-x86_64-0.4.9.jar` (~32MB)
+     - macOS Intel: `video_player-macosx-x86_64-0.4.9.jar` (~24MB)
+     - macOS Apple Silicon (M1/M2/M3/M4): `video_player-macosx-arm64-0.4.9.jar` (~21MB)
+     - Linux 64bit: `video_player-linux-x86_64-0.4.9.jar` (~27MB)
+   - 자기 OS 가 헷갈리면: Windows 는 거의 다 `windows-x86_64`, 인텔맥은 `macosx-x86_64`, 애플 실리콘 맥은 `macosx-arm64`, 리눅스는 `linux-x86_64`.
 
-이전 버전(`video_player-0.4.0.jar`, `0.4.2.jar`, `0.3.x.jar` 등)이 mods 폴더에 남아있다면 **반드시 삭제**하세요. 두 개가 같이 있으면 마인크래프트가 충돌로 켜지지 않습니다.
+이전 버전(`video_player-0.4.0.jar`, `0.4.2.jar`, `0.4.3.jar`, `0.3.x.jar` 등)이 mods 폴더에 남아있다면 **반드시 삭제**하세요. 두 개가 같이 있으면 마인크래프트가 충돌로 켜지지 않습니다. 0.4.7 이하에서 쓰던 JVM 인수(`-Xbootclasspath/a:...javacv...`) 도 0.4.9 부터는 **빼주세요** — 모드 jar 안에 같은 JavaCV 가 들어있어서 부트클래스패스의 것과 충돌해 검은 화면이 날 수 있습니다.
 
-### STEP 5. 영상 재생 라이브러리 (JavaCV) 설치
+### STEP 5. 잘 설치됐는지 확인
-
-여기까지만 하면 마인크래프트는 켜지지만, 영상 자리에 검은 판만 보입니다. 진짜 영상을 재생하려면 **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.3` 만 남기고 다시 시작하세요. (0.4.1 이하는 Fabric 26.1.2 model 로더가 unprefixed `item/generated` parent 를 거부해서 스틱 아이콘이 missing-model 큐브로 보입니다 — 0.4.2 에서 수정됨.)
+- 보라/검정 missing texture 가 나오면 **STEP 4** 에서 이전 버전 jar(`video_player-0.4.0.jar` / `0.4.1.jar` 등)가 mods 폴더에 같이 남아있는 경우입니다. 다 지우고 `0.4.9` 만 남기고 다시 시작하세요. (0.4.1 이하는 Fabric 26.1.2 model 로더가 unprefixed `item/generated` parent 를 거부해서 스틱 아이콘이 missing-model 큐브로 보입니다 — 0.4.2 에서 수정됨.)
 
 ---
 
@@ -164,25 +96,92 @@ Fabric은 마인크래프트에 모드 기능을 추가해 주는 로더입니
 | 명령 | 설명 |
 | --- | --- |
 | `/videostick` | 비디오 스틱 아이템을 인벤토리에 지급 |
-| `/videoplace <url> [w] [h] [loop] [autoplay]` | 정조준한 블록 면에 즉시 영상 배치 |
+| `/videoplace <pos> <facing> <w> <h> <url>` | 좌표에 영상 앵커를 즉시 배치 |
-| `/videodelete` | 정조준한 블록 면의 영상 제거 |
+| `/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
+```
+
+특징:
+
+- **커맨드 블럭에서 사용 가능** — 예: 압력판 → 커맨드 블럭 `/videopreload <url>` 으로 트리거하면 플레이어가 영상 영역에 다가가기 전에 미리 다운로드 시작
+- 명령은 서버에서 실행되지만, 다운로드는 각 **클라이언트**(접속해 있는 모든 플레이어)가 자기 PC 에 받습니다
+- 이미 받아둔 URL 은 재요청해도 다시 다운로드 안 함 (URL 의 SHA-256 으로 캐싱)
+- 한 파일당 상한 512 MB
+- 캐시 폴더가 너무 커지면 직접 `.minecraft/video_player_cache/` 안의 파일을 삭제해도 됩니다 (그러면 다음 사용 시 다시 받아옴)
+
+> 영상 삭제 시 소리가 안 멎던 문제는 0.4.4 에서 수정되었습니다 (앵커 블록이 사라지면 디코더 / 오디오 라인을 즉시 강제 종료). 0.4.5 에서는 `BLOCK_ENTITY_UNLOAD` 이벤트가 누락되는 엣지케이스를 대비해 매 틱마다 BE 존재를 한 번 더 검증합니다.
+
+> 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 모두 등록되어야 함).
+- 영상 자리만 잡히고 검게 보이는 경우: 자신의 OS·CPU 와 다른 플랫폼의 jar 를 받았거나, 이전 버전(0.4.7 이하)의 `-Xbootclasspath/a:...javacv...` JVM 인수가 그대로 남아 있는 경우가 가장 흔합니다. 로그 파일(`.minecraft/logs/latest.log`)에서 `JavaCV not on classpath` WARN 또는 `UnsatisfiedLinkError... jnijavacpp` 메시지로 확인 가능합니다.
 - 0.3.x 이하 버전에서 만든 영상은 새 버전(0.4.x) 에서 보이지 않으니 다시 배치해야 합니다.
 
 ---
 
 ## 개발자용 빌드
 
+바닐라(JavaCV 미포함, 별도 설치 가정) 빌드:
 ```sh
 JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew build
 ```
+산출물: `build/libs/video_player-0.4.9.jar` (~85KB)
 
-산출물: `build/libs/video_player-0.4.3.jar`
+플랫폼별 fat jar (JavaCV 1.5.13 + ffmpeg 8.0.1 네이티브 nested):
+```sh
+JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew clean build -Pplatform=windows-x86_64
+JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew clean build -Pplatform=linux-x86_64
+JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew clean build -Pplatform=macosx-x86_64
+JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew clean build -Pplatform=macosx-arm64
+```
+산출물: `build/libs/video_player-<platform>-0.4.9.jar` (~21-32MB, jar 내부에 nested 로 javacv/javacpp/ffmpeg jar 5개 포함, Fabric loader 가 런타임에 classpath 로 풀어서 로딩)
 
 JavaCV를 직접 의존성으로 가져오는 경우의 Maven 좌표:
 ```

build.gradle

@@ -7,8 +7,25 @@ plugins {
 version = project.mod_version
 group = project.maven_group
 
+// Optional platform bundle target: `-Pplatform=windows-x86_64` etc. produces a fat jar
+// with that platform's JavaCV + FFmpeg natives nested inside via Fabric's `include`
+// directive. Without `-Pplatform`, the build matches pre-0.4.8 behavior (small jar,
+// user supplies JavaCV separately).
+def javacvPlatform = (project.findProperty('platform') ?: '').toString()
+def bundleJavaCv = !javacvPlatform.isEmpty()
+
+def javacvVersion = '1.5.13'
+def ffmpegVersion = '8.0.1-1.5.13'
+def supportedPlatforms = ['windows-x86_64', 'linux-x86_64', 'macosx-x86_64', 'macosx-arm64']
+if (bundleJavaCv && !supportedPlatforms.contains(javacvPlatform)) {
+    throw new GradleException(
+        "Unknown -Pplatform=${javacvPlatform}. Allowed: ${supportedPlatforms.join(', ')}")
+}
+
 base {
-    archivesName = project.archives_base_name
+    archivesName = bundleJavaCv
+        ? "${project.archives_base_name}-${javacvPlatform}"
+        : project.archives_base_name
 }
 
 repositories {
@@ -26,6 +43,19 @@ dependencies {
 
     implementation "net.fabricmc:fabric-loader:${project.loader_version}"
     implementation "net.fabricmc.fabric-api:fabric-api:${project.fabric_version}"
+
+    if (bundleJavaCv) {
+        // Nest the same 5 jars that the README's manual install step used to require, so
+        // users no longer need -Xbootclasspath/a. `include` adds them as jar-in-jar entries;
+        // Fabric loader unpacks and classloads them at runtime.
+        // `transitive = false` keeps us from dragging in opencv/openblas/etc — we only use
+        // FFmpegFrameGrabber / Frame / Java2DFrameConverter.
+        include(implementation("org.bytedeco:javacv:${javacvVersion}") { transitive = false })
+        include(implementation("org.bytedeco:javacpp:${javacvVersion}") { transitive = false })
+        include(implementation("org.bytedeco:ffmpeg:${ffmpegVersion}") { transitive = false })
+        include(implementation("org.bytedeco:javacpp:${javacvVersion}:${javacvPlatform}") { transitive = false })
+        include(implementation("org.bytedeco:ffmpeg:${ffmpegVersion}:${javacvPlatform}") { transitive = false })
+    }
 }
 
 processResources {

gradle.properties

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

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

@@ -10,9 +10,11 @@ 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;
@@ -53,29 +55,47 @@ public class VideoPlayerClient implements ClientModInitializer {
             return InteractionResult.PASS;
         });
 
-        ClientTickEvents.END_CLIENT_TICK.register(client -> {
+        // Pump frame uploads on every render frame (60+Hz) rather than every client tick
-            VideoPlayback.tick();
+        // (20Hz). At 24fps source, a 20Hz pump can skip a frame whenever a tick window happens
-            updateDistanceGains(client);
+        // 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. */
+    /**
+     * 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;
-            double dx = (pos.getX() + 0.5) - eye.x;
+            Vec3 center = be.panelCenter();
-            double dy = (pos.getY() + 0.5) - eye.y;
+            double d = center.distanceTo(eye);
-            double dz = (pos.getZ() + 0.5) - eye.z;
-            double d  = Math.sqrt(dx * dx + dy * dy + dz * dz);
             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);

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);
+    }
+}

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

@@ -3,13 +3,17 @@ 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;
 
@@ -26,11 +30,27 @@ public class VideoPlayerMod implements ModInitializer {
         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);
+        });
+
+        // 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);

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

@@ -8,6 +8,7 @@ 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;
 
 /**
  * Anchor BE — holds per-block config that drives playback.
@@ -52,6 +53,37 @@ public class VideoAnchorBlockEntity extends BlockEntity {
         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();

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

@@ -2,8 +2,10 @@ 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;
@@ -31,5 +33,12 @@ public final class ClientNetworking {
                 }
             });
         });
+
+        // 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());
+        });
     }
 }

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

@@ -29,9 +29,10 @@ import java.util.concurrent.atomic.AtomicReference;
 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;
+    /** {@code AV_PIX_FMT_RGBA} from {@code org.bytedeco.ffmpeg.global.avutil}. */
+    private static final int AV_PIX_FMT_RGBA = 26;
 
     private final Object lock = new Object();
     private Thread worker;
@@ -44,6 +45,20 @@ public class JavaCvBackend implements VideoBackend {
     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) {
@@ -85,6 +100,21 @@ public class JavaCvBackend implements VideoBackend {
 
     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();
@@ -94,10 +124,11 @@ public class JavaCvBackend implements VideoBackend {
     /** Pure-reflection decode loop. Silent fallback if JavaCV isn't present. */
     private void runLoop(String url) {
         Object grabber = null;
-        SourceDataLine audioLine = 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");
@@ -107,17 +138,37 @@ public class JavaCvBackend implements VideoBackend {
             Method getAudioChannels = grabberCls.getMethod("getAudioChannels");
             Method setOpt = grabberCls.getMethod("setOption", String.class, String.class);
             Method setSampleFormat  = grabberCls.getMethod("setSampleFormat", int.class);
+            Method setPixelFormat   = grabberCls.getMethod("setPixelFormat", int.class);
 
-            // HTTP(S) tuning for streaming URLs (e.g. webm via Range / chunked transfer).
+            // HTTP(S) tuning for streaming URLs (webm via Range / chunked transfer).
-            try { setOpt.invoke(grabber, "rw_timeout",         "10000000"); } catch (Throwable ignored) {}
+            // Lower timeouts → close() snaps shut fast when an anchor is deleted mid-stream;
-            try { setOpt.invoke(grabber, "timeout",            "10000000"); } catch (Throwable ignored) {}
+            // larger buffer/probe options → smoother playback when the upstream throttles.
-            try { setOpt.invoke(grabber, "reconnect",          "1");        } catch (Throwable ignored) {}
+            try { setOpt.invoke(grabber, "rw_timeout",          "3000000");   } catch (Throwable ignored) {}
-            try { setOpt.invoke(grabber, "reconnect_streamed", "1");        } catch (Throwable ignored) {}
+            try { setOpt.invoke(grabber, "timeout",             "3000000");   } catch (Throwable ignored) {}
-            try { setOpt.invoke(grabber, "reconnect_at_eof",   "1");        } 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) {}
+            // Force RGBA output so frame.image[0] is a ByteBuffer we can memcpy straight into
+            // the GPU texture. Without this, frame.image[0] is BGR24 and we'd have to round-trip
+            // through Java2DFrameConverter → BufferedImage.getRGB() → per-pixel ARGB→RGBA loop,
+            // which spends 20-50ms of Java work per 1080p frame and was the dominant stutter
+            // source in 0.4.7/0.4.8: when the decoder fell behind real time, the audio buffer
+            // drained, backpressure vanished, and the decoder burst-fired catch-up frames into
+            // the single-slot AtomicReference (dropping all but the last) before the buffer
+            // refilled and blocked it again. swscale's native SIMD does the same conversion in
+            // <1ms per frame, so the decoder consistently keeps real-time pace.
+            try { setPixelFormat.invoke(grabber, AV_PIX_FMT_RGBA); } catch (Throwable ignored) {}
 
             start.invoke(grabber);
             this.width  = (int) getW.invoke(grabber);
@@ -126,20 +177,28 @@ public class JavaCvBackend implements VideoBackend {
 
             int sampleRate    = safeInt(getSampleRate, grabber);
             int audioChannels = safeInt(getAudioChannels, grabber);
-            audioLine = openLine(sampleRate, audioChannels);
+            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);
+            // Java2DFrameConverter is no longer used now that we read RGBA bytes directly,
-            Object converter     = convCls.getDeclaredConstructor().newInstance();
+            // but we still resolve its class so a future code path could fall back to it if a
-            Method toImage       = convCls.getMethod("getBufferedImage", frameCls);
+            // grabber refuses setPixelFormat. Keep the lookup defensive.
 
             while (running.get() && !closed) {
                 if (paused.get()) { Thread.sleep(20); continue; }
-                Object frame = grab.invoke(grabber);
+                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) {
+                    if (loop && running.get() && !closed) {
                         try { stop.invoke(grabber); } catch (Throwable ignored) {}
                         try { start.invoke(grabber); } catch (Throwable ignored) {}
                         continue;
@@ -148,23 +207,30 @@ public class JavaCvBackend implements VideoBackend {
                 }
 
                 Object[] samples = (Object[]) samplesField.get(frame);
-                if (samples != null && samples.length > 0 && audioLine != null) {
+                if (samples != null && samples.length > 0 && localAudioLine != null) {
-                    writeAudio(audioLine, samples, this.gain);
+                    writeAudio(localAudioLine, samples, this.gain);
                 }
 
                 Object[] images = (Object[]) imageField.get(frame);
-                if (images != null && images.length > 0) {
+                if (images != null && images.length > 0 && images[0] instanceof ByteBuffer src) {
-                    java.awt.image.BufferedImage img =
+                    // frame.image[0] is the swscale-converted RGBA plane, reused by the grabber
-                        (java.awt.image.BufferedImage) toImage.invoke(converter, frame);
+                    // across grab() calls. Copy into a fresh direct buffer because the render
-                    if (img != null) {
+                    // thread reads `latest` asynchronously and would otherwise see a buffer
-                        ByteBuffer buf = toRgba(img);
+                    // already being overwritten by the next grab().
-                        if (buf != null) latest.set(buf);
+                    int need = src.remaining();
+                    if (need > 0) {
+                        ByteBuffer copy = ByteBuffer.allocateDirect(need).order(ByteOrder.nativeOrder());
+                        int srcPos = src.position();
+                        copy.put(src);
+                        src.position(srcPos); // restore so JavaCV's own bookkeeping isn't disturbed
+                        copy.flip();
+                        latest.set(copy);
                     }
                 }
 
                 // 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 (audioLine == null) Thread.sleep(15);
+                if (localAudioLine == null) Thread.sleep(15);
             }
         } catch (ClassNotFoundException cnf) {
             VideoPlayerMod.LOG.warn(
@@ -177,11 +243,13 @@ public class JavaCvBackend implements VideoBackend {
             VideoPlayerMod.LOG.warn("[{}] JavaCV decode error: {}", VideoPlayerMod.MOD_ID, t.toString());
         } finally {
             ready = false;
-            if (audioLine != null) {
+            this.audioLine = null;
-                try { audioLine.drain(); } catch (Throwable ignored) {}
+            if (localAudioLine != null) {
-                try { audioLine.stop();  } catch (Throwable ignored) {}
+                try { localAudioLine.stop();  } catch (Throwable ignored) {}
-                try { audioLine.close(); } 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) {}
             }
@@ -194,7 +262,11 @@ public class JavaCvBackend implements VideoBackend {
         try {
             AudioFormat fmt = new AudioFormat(sampleRate, 16, channels, true, false); // signed 16-bit LE
             SourceDataLine line = AudioSystem.getSourceDataLine(fmt);
-            line.open(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) {
@@ -229,24 +301,15 @@ public class JavaCvBackend implements VideoBackend {
                 pcm[idx++] = (byte) ((scaled >> 8) & 0xFF);
             }
         }
-        line.write(pcm, 0, pcm.length);
+        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;
-    }
 }

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";
+        }
+    }
+}

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

@@ -9,8 +9,10 @@ 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;
@@ -58,7 +60,12 @@ public final class VideoPlayback {
         }
 
         VideoBackend backend = WatermediaProbe.isAvailable() ? new WatermediaBackend() : new JavaCvBackend();
-        backend.play(be.getUrl(), be.isLoop());
+        // 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);
@@ -89,11 +96,22 @@ public final class VideoPlayback {
 
     /** Called every client tick to upload new frames into the GPU texture. */
     public static void tick() {
-        if (Minecraft.getInstance() == null) return;
+        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;
@@ -179,25 +197,36 @@ public final class VideoPlayback {
             NativeImage img = texture.getPixels();
             if (img == null) return;
 
-            int pixels = w * h;
+            // RGBA bytes from the backend already match NativeImage's ABGR-int layout when
-            for (int i = 0; i < pixels; i++) {
+            // viewed as little-endian bytes: byte 0 = R (low byte of ABGR int), byte 1 = G,
-                int r = rgba.get() & 0xFF;
+            // byte 2 = B, byte 3 = A. So a flat memcpy works — no per-pixel swap needed.
-                int g = rgba.get() & 0xFF;
+            // This replaces a 2M-iteration Java loop with one native memcpy for 1080p frames,
-                int b = rgba.get() & 0xFF;
+            // cutting upload time from ~20ms to <1ms and removing the main stutter source.
-                int a = rgba.get() & 0xFF;
+            long bytes = (long) w * h * 4L;
-                int abgr = (a << 24) | (b << 16) | (g << 8) | r;
+            MemoryUtil.memCopy(MemoryUtil.memAddress(rgba), img.getPointer(), bytes);
-                img.setPixelABGR(i % w, i / w, abgr);
-            }
             texture.upload();
         }
 
         void close() {
             try { backend.close(); } catch (Throwable ignored) {}
+            // Unregister from TextureManager BEFORE closing the texture itself, so any
+            // straggler binding by Identifier looks up "no such texture" instead of a closed
+            // GL handle (which crashes the renderer on the next frame). Renderer pipelines
+            // can cache RenderType objects keyed by Identifier across frames, and on delete
+            // the old anchor's frame can still be in flight in the submit buffer when its
+            // texture closes — without this release(), the bind would dereference a freed
+            // GL handle.
+            if (registered) {
+                Minecraft mc = Minecraft.getInstance();
+                if (mc != null) {
+                    try { mc.getTextureManager().release(id); } catch (Throwable ignored) {}
+                }
+                registered = false;
+            }
             if (texture != null) {
                 try { texture.close(); } catch (Throwable ignored) {}
                 texture = null;
             }
-            // texture manager keeps the registration; the texture itself is closed.
         }
     }
 }

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;
+    }
+}

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;
+    }
+}

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

@@ -24,6 +24,7 @@ public final class VideoPlayerNetwork {
         // 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);