11 Commits

Author SHA1 Message Date
tkrmagid
d34dc97671 v0.4.6: server config for auto-preload on join
Some checks failed
build / build (push) Has been cancelled
- 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
- 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
- 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
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
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
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
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
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
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
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
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
16 changed files with 853 additions and 56 deletions

255
README.md
View File

@@ -1,29 +1,248 @@
# video_player (영상재생모드)
마인크래프트(Fabric, MC 1.21.6+) 안에서 임의의 mp4 URL을 블록 표면에 재생하는 모드.
마인크래프트 안에서 임의의 동영상 URL을 벽·바닥·천장에 평면으로 재생하는 Fabric 모드.
- 모드 ID: `video_player`
- 한글명: 영상재생모드
- 로더: Fabric (싱글플레이어 / 전용 서버 양쪽 지원)
- 명세: 별도 SPEC 문서 참조
- 현재 버전: **0.4.6**
- 마인크래프트 버전: **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.6.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.6` 만 남기고 다시 시작하세요. (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.6.jar`
JavaCV를 직접 의존성으로 가져오는 경우의 Maven 좌표:
```
org.bytedeco:javacv-platform:1.5.13
```

View File

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

View File

@@ -10,6 +10,7 @@ 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;
@@ -62,20 +63,33 @@ public class VideoPlayerClient implements ClientModInitializer {
// 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;
double dy = (pos.getY() + 0.5) - eye.y;
double dz = (pos.getZ() + 0.5) - eye.z;
double d = Math.sqrt(dx * dx + dy * dy + dz * dz);
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);

View File

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

View File

@@ -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);

View File

@@ -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();

View File

@@ -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());
});
}
}

View File

@@ -44,6 +44,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 +99,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 +123,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");
@@ -108,12 +138,21 @@ public class JavaCvBackend implements VideoBackend {
Method setOpt = grabberCls.getMethod("setOption", String.class, String.class);
Method setSampleFormat = grabberCls.getMethod("setSampleFormat", int.class);
// HTTP(S) tuning for streaming URLs (e.g. webm via Range / chunked transfer).
try { setOpt.invoke(grabber, "rw_timeout", "10000000"); } catch (Throwable ignored) {}
try { setOpt.invoke(grabber, "timeout", "10000000"); } 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) {}
// 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.
@@ -126,7 +165,8 @@ 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");
@@ -137,9 +177,16 @@ public class JavaCvBackend implements VideoBackend {
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,8 +195,8 @@ public class JavaCvBackend implements VideoBackend {
}
Object[] samples = (Object[]) samplesField.get(frame);
if (samples != null && samples.length > 0 && audioLine != null) {
writeAudio(audioLine, samples, this.gain);
if (samples != null && samples.length > 0 && localAudioLine != null) {
writeAudio(localAudioLine, samples, this.gain);
}
Object[] images = (Object[]) imageField.get(frame);
@@ -164,7 +211,7 @@ public class JavaCvBackend implements VideoBackend {
// 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 +224,13 @@ public class JavaCvBackend implements VideoBackend {
VideoPlayerMod.LOG.warn("[{}] JavaCV decode error: {}", VideoPlayerMod.MOD_ID, t.toString());
} finally {
ready = false;
if (audioLine != null) {
try { audioLine.drain(); } catch (Throwable ignored) {}
try { audioLine.stop(); } catch (Throwable ignored) {}
try { audioLine.close(); } catch (Throwable ignored) {}
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) {}
}
@@ -194,7 +243,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,7 +282,11 @@ 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) {

View File

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

View File

@@ -11,6 +11,7 @@ import net.minecraft.core.BlockPos;
import net.minecraft.resources.Identifier;
import java.nio.ByteBuffer;
import java.nio.file.Path;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Iterator;
@@ -58,7 +59,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 +95,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;

View File

@@ -67,9 +67,11 @@ public class VideoAnchorRenderer implements BlockEntityRenderer<VideoAnchorBlock
pose.translate(0.5F, 0.5F, 0.5F);
// 2) Rotate local +Z to align with the wall's outward normal.
applyFaceRotation(pose, f);
// 3) Center the quad on origin (local XY) and push it back 0.5 - ε so it lands on the
// wall surface (the boundary face between the anchor's air block and the wall block).
pose.translate(-w / 2.0F, -h / 2.0F, -0.5F + SURFACE_EPSILON);
// 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);
@@ -89,15 +91,21 @@ public class VideoAnchorRenderer implements BlockEntityRenderer<VideoAnchorBlock
pose.popPose();
}
/** Rotate so local +Z (the quad's outward normal in its base orientation) becomes world {@code f}. */
/**
* 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 already faces world +Z (south) */ }
case NORTH -> pose.mulPose(Axis.YP.rotationDegrees(180F));
case EAST -> pose.mulPose(Axis.YP.rotationDegrees(-90F));
case WEST -> pose.mulPose(Axis.YP.rotationDegrees(90F));
case UP -> pose.mulPose(Axis.XP.rotationDegrees(-90F));
case DOWN -> pose.mulPose(Axis.XP.rotationDegrees(90F));
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)
}
}

View File

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

View File

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

View File

@@ -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);

View File

@@ -0,0 +1,6 @@
{
"model": {
"type": "minecraft:model",
"model": "video_player:item/video_stick"
}
}

View File

@@ -1,5 +1,5 @@
{
"parent": "item/generated",
"parent": "minecraft:item/generated",
"textures": {
"layer0": "video_player:item/video_stick"
}