docs: refresh README for 0.4.32–0.4.35 changes
All checks were successful
build / build (push) Successful in 1m22s

- Document the configurable audio channel: video audio now plays through the
  RECORDS ("주크박스/음반") slider by default (0.4.32), tunable via sound_category
  in config/video_player.json.
- Note the 0.4.33 fix for the audio-plays-but-screen-is-black bug on widths not
  aligned to 16px (swscale linesize padding).
- Note 0.4.31 non-player (command block/console/function) permission bypass.
- Bump version references 0.4.12 → 0.4.35 (current release, jar names, dev build
  outputs); keep the historical "since 0.4.12" notes intact.

Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>
This commit is contained in:
tkrmagid
2026-06-05 02:26:33 +09:00
parent ad9d15da9e
commit d8974afbcf

View File

@@ -3,7 +3,7 @@
마인크래프트 안에서 임의의 동영상 URL을 벽·바닥·천장에 평면으로 재생하는 Fabric 모드.
- 모드 ID: `video_player`
- 현재 버전: **0.4.12**
- 현재 버전: **0.4.35**
- 마인크래프트 버전: **26.1.2**
- 필요 Java: **25** (마인크래프트 26.x 가 요구함)
@@ -54,10 +54,10 @@ Fabric은 마인크래프트에 모드 기능을 추가해 주는 로더입니
2. **video_player** (이 모드, 0.4.12 부터 JavaCV 가 jar 안에 포함됨)
- 다운로드: https://git.tkrmagid.kr/tkrmagid/mc_video_player_mod/releases
- 자신의 OS·CPU 에 맞는 jar **한 개** 만 받아서 `mods` 폴더에 넣으면 됩니다 (별도 JavaCV 설치 불필요):
- Windows 64bit: `video_player-windows-x86_64-0.4.12.jar` (~32MB)
- macOS Intel: `video_player-macosx-x86_64-0.4.12.jar` (~24MB)
- macOS Apple Silicon (M1/M2/M3/M4): `video_player-macosx-arm64-0.4.12.jar` (~21MB)
- Linux 64bit: `video_player-linux-x86_64-0.4.12.jar` (~27MB)
- Windows 64bit: `video_player-windows-x86_64-0.4.35.jar` (~33MB)
- macOS Intel: `video_player-macosx-x86_64-0.4.35.jar` (~25MB)
- macOS Apple Silicon (M1/M2/M3/M4): `video_player-macosx-arm64-0.4.35.jar` (~21MB)
- Linux 64bit: `video_player-linux-x86_64-0.4.35.jar` (~28MB)
- 자기 OS 가 헷갈리면: Windows 는 거의 다 `windows-x86_64`, 인텔맥은 `macosx-x86_64`, 애플 실리콘 맥은 `macosx-arm64`, 리눅스는 `linux-x86_64`.
이전 버전(`video_player-0.4.0.jar`, `0.4.2.jar`, `0.4.3.jar`, `0.3.x.jar` 등)이 mods 폴더에 남아있다면 **반드시 삭제**하세요. 두 개가 같이 있으면 마인크래프트가 충돌로 켜지지 않습니다. 0.4.7 이하에서 쓰던 JVM 인수(`-Xbootclasspath/a:...javacv...`) 도 0.4.12 부터는 **빼주세요** — 모드 jar 안에 같은 JavaCV 가 들어있어서 부트클래스패스의 것과 충돌해 검은 화면이 날 수 있습니다.
@@ -67,7 +67,7 @@ Fabric은 마인크래프트에 모드 기능을 추가해 주는 로더입니
게임 안에서 채팅창에 `/videostick` 을 입력하세요. 정상이라면:
- 인벤토리에 **비디오 스틱** 아이템이 들어옵니다 (보라/검정 missing-texture 가 아니라 작대기 모양 아이콘).
- 보라/검정 missing texture 가 나오면 **STEP 4** 에서 이전 버전 jar(`video_player-0.4.0.jar` / `0.4.1.jar` 등)가 mods 폴더에 같이 남아있는 경우입니다. 다 지우고 `0.4.12` 만 남기고 다시 시작하세요. (0.4.1 이하는 Fabric 26.1.2 model 로더가 unprefixed `item/generated` parent 를 거부해서 스틱 아이콘이 missing-model 큐브로 보입니다 — 0.4.2 에서 수정됨.)
- 보라/검정 missing texture 가 나오면 **STEP 4** 에서 이전 버전 jar(`video_player-0.4.0.jar` / `0.4.1.jar` 등)가 mods 폴더에 같이 남아있는 경우입니다. 다 지우고 `0.4.35` 만 남기고 다시 시작하세요. (0.4.1 이하는 Fabric 26.1.2 model 로더가 unprefixed `item/generated` parent 를 거부해서 스틱 아이콘이 missing-model 큐브로 보입니다 — 0.4.2 에서 수정됨.)
---
@@ -101,7 +101,15 @@ Fabric은 마인크래프트에 모드 기능을 추가해 주는 로더입니
| `/videomute <pos> <on\|off>` | 영상의 음소거 켜고/끄기 |
| `/videopreload <url>` | URL 을 미리 받아 디스크 캐시에 저장 (자세한 내용은 아래) |
`/videoplace`, `/videodelete`, `/videomute`, `/videopreload` 는 기본적으로 OP(권한 레벨 2) 가 필요하므로 **커맨드 블럭에서도 그대로 호출 가능합니다**. 커맨드 블럭은 기본이 권한 레벨 2 라 별도 설정 없이 동작합니다.
`/videoplace`, `/videodelete`, `/videomute`, `/videopreload` 는 기본적으로 OP(권한 레벨 2) 가 필요하므로 **커맨드 블럭에서도 그대로 호출 가능합니다**. 커맨드 블럭은 기본이 권한 레벨 2 라 별도 설정 없이 동작합니다. (0.4.31 부터 커맨드 블럭·콘솔·함수 등 비(非)플레이어 실행자는 `functionPermissionLevel` 게임룰을 건드리지 않아도 호출됩니다.)
### 소리(오디오) 설정 (0.4.32+)
영상 소리는 마인크래프트 **음량 슬라이더**의 영향을 받습니다. 0.4.32 부터 기본값은 **"주크박스/음반"(record)** 슬라이더입니다 — 영상은 미디어 재생이라 음악·효과음과 따로 조절하라고 이 채널을 씁니다. (마스터 슬라이더는 항상 위에서 한 번 더 곱해집니다.)
어떤 슬라이더가 영상 소리를 제어할지는 `config/video_player.json``sound_category` 로 바꿀 수 있습니다 (클라이언트별 설정). 가능한 값: `master, music, record, weather, block, hostile, neutral, player, ambient, voice, ui`. 기본값은 `record` 이고, 잘못된 값을 적으면 경고 로그를 남기고 `record` 로 동작합니다.
소리 크기는 **판때기 중앙**으로부터의 거리로 감쇠되며(16블록에서 0), `/videomute <pos> <on|off>` 로 개별 영상을 음소거할 수 있습니다.
### `/videopreload` — 영상 미리 로딩 (스터터 제거)
@@ -162,6 +170,7 @@ Fabric은 마인크래프트에 모드 기능을 추가해 주는 로더입니
## 알려진 이슈
- 영상 자리만 잡히고 검게 보이는 경우: 자신의 OS·CPU 와 다른 플랫폼의 jar 를 받았거나, 이전 버전(0.4.7 이하)의 `-Xbootclasspath/a:...javacv...` JVM 인수가 그대로 남아 있는 경우가 가장 흔합니다. 로그 파일(`.minecraft/logs/latest.log`)에서 `JavaCV not on classpath` WARN 또는 `UnsatisfiedLinkError... jnijavacpp` 메시지로 확인 가능합니다.
- (0.4.33 에서 수정됨) 소리는 나오는데 화면만 검게 나오던 문제: 가로 픽셀 수가 16의 배수가 아닌 해상도의 영상(예: 1674×1080)에서 디코더 행 패딩(swscale linesize 정렬) 때문에 모든 프레임이 버려지던 버그였습니다. **0.4.33 이상**으로 올리면 해결됩니다.
- 0.3.x 이하 버전에서 만든 영상은 새 버전(0.4.x) 에서 보이지 않으니 다시 배치해야 합니다.
---
@@ -172,7 +181,7 @@ Fabric은 마인크래프트에 모드 기능을 추가해 주는 로더입니
```sh
JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew build
```
산출물: `build/libs/video_player-0.4.12.jar` (~85KB)
산출물: `build/libs/video_player-0.4.35.jar` (~106KB)
플랫폼별 fat jar (JavaCV 1.5.13 + ffmpeg 8.0.1 네이티브 nested):
```sh
@@ -181,7 +190,7 @@ JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew clean build -Pplatform=li
JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew clean build -Pplatform=macosx-x86_64
JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew clean build -Pplatform=macosx-arm64
```
산출물: `build/libs/video_player-<platform>-0.4.12.jar` (~21-32MB, jar 내부에 nested 로 javacv/javacpp/ffmpeg jar 5개 포함, Fabric loader 가 런타임에 classpath 로 풀어서 로딩)
산출물: `build/libs/video_player-<platform>-0.4.35.jar` (~21-33MB, jar 내부에 nested 로 javacv/javacpp/ffmpeg jar 5개 포함, Fabric loader 가 런타임에 classpath 로 풀어서 로딩)
JavaCV를 직접 의존성으로 가져오는 경우의 Maven 좌표:
```