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 — 정조준한 영상 제거

빌드 (개발자)

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 백엔드만 동작).