mc_video_player_mod/README.md

# video_player (영상재생모드)

마인크래프트 안에서 임의의 동영상 URL을 벽·바닥·천장에 평면으로 재생하는 Fabric 모드.

- 모드 ID: `video_player`
- 현재 버전: **0.4.35**
- 마인크래프트 버전: **26.1.2**
- 필요 Java: **25** (마인크래프트 26.x 가 요구함)

---

## 처음 사용하는 분을 위한 설치 가이드

이 모드는 마인크래프트 **공식 런처**에 **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** (이 모드, 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.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 가 들어있어서 부트클래스패스의 것과 충돌해 검은 화면이 날 수 있습니다.

### STEP 5. 잘 설치됐는지 확인

게임 안에서 채팅창에 `/videoStick` 을 입력하세요 (대소문자 구분). 정상이라면:

- 인벤토리에 **비디오 스틱** 아이템이 들어옵니다 (보라/검정 missing-texture 가 아니라 작대기 모양 아이콘).
- 보라/검정 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 에서 수정됨.)

---

## 사용법

### 영상 배치

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` 처럼 camelCase).

| 명령 | 설명 |
| --- | --- |
| `/videoStick` | 비디오 스틱 아이템을 인벤토리에 지급 (플레이어만) |
| `/videoPlace <pos> <facing> <w> <h> <url-or-name>` | 좌표에 영상 앵커 배치 (볼륨 50%·음소거 해제). `url-or-name` 은 http(s) URL 또는 `/videoCache add` 로 등록한 이름 |
| `/videoPlace <pos> <facing> <w> <h> <volume> <url-or-name>` | 위와 같지만 볼륨 지정: `0`~`100` (%) 또는 `-1`(음소거로 시작) |
| `/videoDelete <pos>` | 좌표의 영상 앵커 제거 |
| `/videoMute <pos> <on\|off>` | 영상의 음소거 켜고/끄기 |
| `/videoCache add <name> <url>` | 자주 쓰는 URL 을 이름으로 등록 (서버 config 에 저장, 접속자에게 자동 프리로드) |
| `/videoCache list` | 등록된 이름·URL 목록 표시 |
| `/videoCache remove <name>` | 등록된 이름 1개 삭제 |
| `/videoCache clear` | 등록된 이름 전체 삭제 |

- `facing` 은 `north/south/east/west/up/down`, `w`·`h` 는 `1`~`32` 블록.
- 모든 `/video*` 명령은 기본적으로 OP(권한 레벨 2) 가 필요하므로 **커맨드 블럭·콘솔에서도 그대로 호출 가능합니다**. 커맨드 블럭은 기본이 권한 레벨 2 라 별도 설정 없이 동작합니다. (0.4.31 부터 커맨드 블럭·콘솔·함수 등 비(非)플레이어 실행자는 `functionPermissionLevel` 게임룰을 건드리지 않아도 호출됩니다.)
- `/videoStick` 만 플레이어 전용입니다(인벤토리에 아이템을 줘야 하므로).

### 소리(오디오) 설정 (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>` 로 개별 영상을 음소거할 수 있습니다.

### `/videoCache` — 영상 미리 로딩 (스터터 제거)

스트리밍 URL 을 라이브로 받으면서 재생하면 네트워크가 잠깐 느려질 때 끊김이 생깁니다. `/videoCache add <name> <url>` 로 URL 을 이름과 함께 등록해 두면, 접속해 있는 모든 클라이언트가 백그라운드에서 그 URL 을 통째로 다운로드해 로컬 캐시에 저장하고, 같은 URL(또는 그 이름)로 영상이 재생될 때 인터넷이 아니라 로컬 파일을 사용합니다 (= 끊김 없음).

```
/videoCache add intro https://video.example.com/foo.mp4
/videoPlace 10 64 10 north 4 3 intro          # 등록한 이름을 URL 자리에 그대로 사용
```

특징:

- **커맨드 블럭·콘솔에서 사용 가능** — 예: 서버 시작 시 함수로 `/videoCache add ...` 를 등록해 두면 접속자가 영상에 다가가기 전에 미리 다운로드가 시작됩니다
- 명령은 서버에서 실행되지만, 다운로드는 각 **클라이언트**(접속한 모든 플레이어)가 자기 PC 에 받습니다
- 등록한 이름은 서버 config(`config/video_player.json` 의 `cache_entries`)에 저장되어 **재시작 후에도 유지**되고, 새로 접속하는 플레이어에게도 자동으로 전달됩니다
- 이미 받아둔 URL 은 재요청해도 다시 다운로드하지 않습니다 (URL 의 SHA-256 으로 캐싱)
- 한 영상당 / 전체 캐시 용량 상한은 config 의 `max_preload_mb` / `max_cache_mb` 로 정합니다 (아래 참고)
- `/videoCache remove <name>` 하면 다운로드 중인 항목까지 취소되고 해당 캐시 파일이 삭제됩니다 (0.4.34)
- 클라이언트 캐시는 **게임 종료 시 자동으로 비워집니다**. 등록 항목은 서버에 남아 있으므로 다음 접속 때 다시 받아옵니다 — 캐시 폴더를 수동으로 지울 필요가 없습니다

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

> 다운로드 시작 / 완료 / 실패는 `[videopreload]` 채팅 메시지로 표시됩니다. 커맨드블럭/함수로 `/videoCache add` 후 `/videoPlace` 를 이어 실행할 때는 `[videopreload] 완료` 메시지를 본 뒤에 재생해야 로컬 파일에서 재생됩니다 (그 전에 재생하면 일반 스트리밍으로 떨어집니다).

### 서버 config (`config/video_player.json`)

서버(싱글플레이는 통합 서버)에 모드를 넣고 한 번 실행하면 `config/video_player.json` 이 자동 생성됩니다. 기본 생성 내용:

```json
{
  "_comment": "max_preload_mb: ... cache_entries: named entries managed by /videoCache add|list|remove.",
  "max_preload_mb": 2048,
  "max_cache_mb": 750,
  "render_distance_blocks": 128,
  "sound_category": "record",
  "preload_urls": [],
  "cache_entries": []
}
```

키 설명:

- `max_preload_mb` — 클라이언트가 영상 **한 개**를 받을 때의 상한(MB). 초과하면 그 다운로드를 중단합니다. 기본 2048.
- `max_cache_mb` — 클라이언트 **전체 캐시 폴더**의 상한(MB). 기본 750.
- `render_distance_blocks` — 영상 앵커가 렌더링되는 최대 거리(블록). 기본 128.
- `sound_category` — 영상 오디오를 어느 음량 슬라이더로 제어할지 (위 "소리 설정" 참고). 기본 `record`.
- `cache_entries` — `/videoCache add|list|remove` 로 관리되는 **이름 있는** 자동 프리로드 목록. 예: `[{ "name": "intro", "url": "https://video.example.com/intro.mp4" }]`. 직접 편집보다 명령어 사용을 권장합니다(명령어는 즉시 반영·접속자에게 즉시 브로드캐스트).
- `preload_urls` — 이름 없는 레거시 자동 프리로드 목록(하위호환). 접속 시 모든 플레이어가 받습니다. 각 URL 은 `http(s)://` 시작, 256자 이하.

규칙:

- `cache_entries` 는 명령어로 바꾸면 즉시 저장·반영됩니다. `preload_urls` 등 파일을 직접 수정한 경우엔 **서버 재시작** 이 필요합니다(파일은 시작 시 1회 로딩).
- 이미 캐시된 URL 은 다시 다운로드하지 않습니다 (SHA-256 캐시 키).
- 싱글플레이도 통합 서버의 `config/video_player.json` 에 동일하게 동작합니다.

---

## 알려진 이슈

- 영상 자리만 잡히고 검게 보이는 경우: 자신의 OS·CPU 와 다른 플랫폼의 jar 를 받았거나, 이전 버전(0.4.7 이하)의 `-Xbootclasspath/a:...javacv...` JVM 인수가 그대로 남아 있는 경우가 가장 흔합니다. 로그 파일(`.minecraft/logs/latest.log`)에서 `JavaCV not on classpath` WARN 또는 `UnsatisfiedLinkError... jnijavacpp` 메시지로 확인 가능합니다.
- (0.4.33 에서 수정됨) 소리는 나오는데 화면만 검게 나오던 문제: 가로 픽셀 수가 16의 배수가 아닌 해상도의 영상(예: 1674×1080)에서 디코더 행 패딩(swscale linesize 정렬) 때문에 모든 프레임이 버려지던 버그였습니다. **0.4.33 이상**으로 올리면 해결됩니다.
- 0.3.x 이하 버전에서 만든 영상은 새 버전(0.4.x) 에서 보이지 않으니 다시 배치해야 합니다.

---

## 개발자용 빌드

바닐라(JavaCV 미포함, 별도 설치 가정) 빌드:
```sh
JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew build
```
산출물: `build/libs/video_player-0.4.35.jar` (~106KB)

플랫폼별 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.35.jar` (~21-33MB, jar 내부에 nested 로 javacv/javacpp/ffmpeg jar 5개 포함, Fabric loader 가 런타임에 classpath 로 풀어서 로딩)

JavaCV를 직접 의존성으로 가져오는 경우의 Maven 좌표:
```
org.bytedeco:javacv-platform:1.5.13
```