video_player (영상재생모드)

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

• 모드 ID: video_player
• 현재 버전: 0.4.7
• 마인크래프트 버전: 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 (이 모드)
   • 다운로드: https://git.tkrmagid.kr/tkrmagid/mc_video_player_mod/releases
   • video_player-0.4.7.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.7 만 남기고 다시 시작하세요. (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

특징:

• 커맨드 블럭에서 사용 가능 — 예: 압력판 → 커맨드 블럭 /videopreload <url> 으로 트리거하면 플레이어가 영상 영역에 다가가기 전에 미리 다운로드 시작
• 명령은 서버에서 실행되지만, 다운로드는 각 클라이언트(접속해 있는 모든 플레이어)가 자기 PC 에 받습니다
• 이미 받아둔 URL 은 재요청해도 다시 다운로드 안 함 (URL 의 SHA-256 으로 캐싱)
• 한 파일당 상한 512 MB
• 캐시 폴더가 너무 커지면 직접 .minecraft/video_player_cache/ 안의 파일을 삭제해도 됩니다 (그러면 다음 사용 시 다시 받아옴)

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

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

0.4.5 부터 오디오 거리 감쇠가 판때기 중앙을 기준으로 계산됩니다. 예전엔 앵커 블록(보통 화면 모서리)을 기준으로 측정해서 큰 화면일수록 소리가 한쪽에서 들리는 느낌이었습니다.

서버 config 로 자동 프리로드 (0.4.6+)

서버에 모드를 넣고 한 번 실행하면 <서버폴더>/config/video_player.json 가 자동 생성됩니다. 이 파일에 자주 쓰는 영상 URL 을 적어두면, 플레이어가 접속할 때마다 서버가 자동으로 그 URL 들의 프리로드 요청을 보냅니다 (= /videopreload 를 사람마다 친 것과 같음).

기본 생성된 파일 예시:

{
  "_comment": "preload_urls: HTTP(S) video URLs broadcast to every player on join. ...",
  "preload_urls": []
}

사용 예시 — 인트로 영상과 BGM 영상을 모든 접속자가 미리 받도록:

{
  "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) 에서 보이지 않으니 다시 배치해야 합니다.

---

개발자용 빌드

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

산출물: build/libs/video_player-0.4.7.jar

JavaCV를 직접 의존성으로 가져오는 경우의 Maven 좌표:

org.bytedeco:javacv-platform:1.5.13