mc_video_player_mod/README.md

video_player (영상재생모드)

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

• 모드 ID: video_player
• 현재 버전: 0.4.2
• 마인크래프트 버전: 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.2.jar 를 다운로드해서 같은 mods 폴더에 넣습니다.

이전 버전(video_player-0.4.0.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 4개를 한꺼번에 선택해서 추가
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 4개를 골라 둡니다 (다른 파일은 안 씁니다):
     • javacv.jar
     • javacpp.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. 이 4개 jar 를 게임이 읽도록 등록

   • 가장 안전한 위치: .minecraft/libraries/javacv/ 폴더를 새로 만들고 4개 jar를 거기에 복사하세요.

   • 그 다음, 공식 런처에서 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\ffmpeg.jar;C:\Users\홍길동\AppData\Roaming\.minecraft\libraries\javacv\ffmpeg-windows-x86_64.jar
     

     (C:\Users\<본인 윈도우 사용자명>\AppData\Roaming\ 부분을 본인 사용자 폴더로 바꾸세요. 윈도우키+R → cmd → echo %APPDATA% 로 정확한 경로 확인 가능.)

     macOS:

     -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/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/ffmpeg.jar:/home/사용자이름/.minecraft/libraries/javacv/ffmpeg-linux-x86_64.jar
     

     주의:

     • Windows는 jar 사이를 세미콜론(;) 으로 구분합니다.
     • macOS/Linux는 콜론(:) 으로 구분합니다.
     • 경로에 띄어쓰기가 있으면(특히 macOS의 Application Support) 전체 인수를 큰따옴표로 감싸세요.
     • 사용자이름 부분은 실제 자신의 사용자 폴더 이름으로 바꾸세요.
     • ffmpeg-... 부분의 jar 이름은 OS에 맞춰 1번에서 고른 그 파일명 그대로 적습니다 (zip 안에는 ffmpeg-windows-x86_64.jar 같은 짧은 이름으로 들어있습니다).

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.2 만 남기고 다시 시작하세요. (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 <url> [w] [h] [loop] [autoplay]	정조준한 블록 면에 즉시 영상 배치
/videodelete	정조준한 블록 면의 영상 제거

---

알려진 이슈

• JavaCV가 안 잡혀있으면 영상 자리만 잡힐 뿐 검게 보입니다. 로그 파일(.minecraft/logs/latest.log)에서 JavaCV not on classpath WARN 메시지로 확인 가능합니다.
• 0.3.x 이하 버전에서 만든 영상은 새 버전(0.4.x) 에서 보이지 않으니 다시 배치해야 합니다.

---

개발자용 빌드

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

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

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

org.bytedeco:javacv-platform:1.5.13