# video_player (영상재생모드)

마인크래프트(Fabric, MC 26.1.2) 안에서 임의의 http/https mp4·webm URL을 블록 표면에 재생하는 클라이언트/서버 양립 모드.

- 모드 ID: `video_player`
- 한글명: 영상재생모드
- 현재 버전: **0.4.1**
- 타겟: Minecraft **26.1.2** (Mojmap, intermediary/Yarn 단종 이후 단일 타겟)
- 로더: Fabric Loader **0.19.2** 이상
- Java: **25** (Minecraft 26.x 요구사항)

## 클라이언트 설치

### 1. 필수 의존성

순서대로 `mods/` 폴더에 넣으세요.

1. **Fabric Loader 0.19.2+**
   https://fabricmc.net/use/installer/
2. **Fabric API 0.149.0+26.1.2 (이상)**
   https://modrinth.com/mod/fabric-api/versions?g=26.1.2
3. **video_player-0.4.1.jar** (이 모드)
   https://git.tkrmagid.kr/tkrmagid/mc_video_player_mod/releases

### 2. 영상 재생 라이브러리 (JavaCV) — **필수**

JavaCV가 없으면 모드는 로드되지만 영상은 재생되지 않습니다(앵커 자리만 표시). FFmpeg 8.0.1이 동봉된 **JavaCV 1.5.13** (2026-02-22 릴리스)을 권장합니다.

#### 방법 A — Prism Launcher / MultiMC (권장)

런처에서 인스턴스 → 편집 → **Version → Add to Minecraft.jar (Java libraries)** 로 아래 jar들을 추가하세요. 이 방식은 클래스패스에 라이브러리로 등록되므로 모드 폴더에 넣는 것보다 안정적입니다.

1. JavaCV 1.5.13 바이너리 zip 다운로드:
   https://github.com/bytedeco/javacv/releases/download/1.5.13/javacv-platform-1.5.13-bin.zip
2. 압축 해제 후 다음 jar를 추가:
   - `javacv.jar`
   - `javacpp.jar`
   - `ffmpeg.jar`
   - 자신의 OS에 맞는 ffmpeg 네이티브 1개:
     - Windows: `ffmpeg-8.0.1-1.5.13-windows-x86_64.jar`
     - Linux: `ffmpeg-8.0.1-1.5.13-linux-x86_64.jar`
     - macOS Intel: `ffmpeg-8.0.1-1.5.13-macosx-x86_64.jar`
     - macOS Apple Silicon: `ffmpeg-8.0.1-1.5.13-macosx-arm64.jar`

#### 방법 B — 공식 런처 (JVM args)

공식 런처는 `mods/` 폴더의 일반 jar를 라이브러리로 자동 로드하지 않습니다. 직접 클래스패스에 추가하려면 jar 위치를 정한 뒤 게임 실행 인자(JVM args)에 다음을 더하세요:

```
-Xss4M -Dorg.lwjgl.system.allocator=system
-cp /절대경로/javacv.jar:/절대경로/javacpp.jar:/절대경로/ffmpeg.jar:/절대경로/ffmpeg-8.0.1-1.5.13-linux-x86_64.jar
```

Windows는 `:` 대신 `;` 구분자. 이 방식은 까다로워서 **Prism/MultiMC 사용을 강하게 권장합니다.**

#### 방법 C — Maven 좌표 (직접 빌드 / 모드팩 제작자)

```
org.bytedeco:javacv-platform:1.5.13          # 모든 플랫폼 ffmpeg 포함 (~500MB)
  또는
org.bytedeco:javacv:1.5.13
org.bytedeco:ffmpeg-platform:8.0.1-1.5.13    # ffmpeg만
```

## 사용법

### 영상 배치

1. 인벤토리에서 **비디오 스틱** 획득 (`/videostick`)
2. 원하는 벽/바닥/천장 블록을 비디오 스틱으로 **우클릭**
3. 열린 GUI에 URL·너비·높이·반복·자동재생 입력
4. 클릭한 블록이 영상의 **왼쪽 아래** 모서리가 되고, 너비 W × 높이 H 만큼 오른쪽/위로 펼쳐집니다 (벽면에 딱 붙음).

### 영상 수정 / 삭제

- 이미 영상이 걸린 벽면을 비디오 스틱으로 **우클릭** → GUI 재오픈
- **쉬프트 + 좌클릭**으로 영상 삭제 (앵커가 인접 공기 블록에 숨어 있어 일반 좌클릭으로는 안 지워집니다)

### URL 요구사항

- `http://` 또는 `https://`만
- 길이 256자 이하
- FFmpeg가 디코드할 수 있는 컨테이너/코덱 (mp4, webm, mkv, mov 등)
- Range/Chunked 응답을 지원하는 서버 권장
- 인증 토큰이 URL에 포함된 경우 GUI 보호되지만 평문 저장됨에 주의

### 명령어

- `/videostick` — 비디오 스틱 지급
- `/videoplace <url> [w] [h] [loop] [autoplay]` — 정조준한 블록면에 영상 배치
- `/videodelete` — 정조준한 영상 제거

## 빌드 (개발자)

```sh
JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew build
```

산출물: `build/libs/video_player-0.4.1.jar`

## 알려진 이슈

- JavaCV가 없으면 영상 영역에 자리만 잡힐 뿐 그려지지 않습니다 (로그에 `WARN ... JavaCV not on classpath` 출력).
- 0.3.x 이하에서 만든 비주얼 앵커 블록은 0.4.0 이후 보이지 않습니다 — 다시 배치하세요.
- WaterMedia 백엔드는 26.1.2 포트가 나오기 전까진 더미 상태입니다 (JavaCV 백엔드만 동작).