TL;DR

  • HuskVault는 HuskHoard와 연동해 콜드 미디어 아카이브의 메타데이터를 NVMe에 보존하고, 장착된 저장 매체에서 영상을 직접 스트리밍하는 개인용 영화관 프런트엔드임.
  • 영화 포스터·줄거리·파일 기록은 실제 미디어가 보관 중일 때도 빠른 NVMe 드라이브에 캐시됨.
  • 아카이브 드라이브, 광디스크 바인더와 LTO 테이프는 유휴 상태에서 대기 전력 0W를 사용하며, BD-R과 M-DISC 지원은 아직 테스트 중임.
  • 오프라인 영화 선택 시 바인더 슬롯·디스크 번호·볼륨 UUID를 안내하고, 장착 후에는 HTTP 206 바이트 범위 요청으로 압축 해제 없이 직접 재생함.
  • TMDb 검색 기반 Fix Match 기능으로 제목을 수정하면서 실제 저장 위치 정보를 보존함.

개요

  • HuskVault는 콜드 티어 미디어 아카이브를 위해 설계된 경량 영화관 프런트엔드이자 메타데이터 오케스트레이터로, HuskHoard 커널 데몬과 직접 연동해 물리 저장 매체에 스트리밍 서비스와 유사한 화면을 제공함.
  • 영화 포스터·줄거리·파일 기록은 실제 미디어 데이터가 콜드 저장 매체에 보관된 동안에도 빠른 NVMe 드라이브에 영구 캐시됨.
  • 아카이브 드라이브, 광디스크 바인더(BD-R/M-DISC, 지원 여부 테스트 중), LTO 테이프는 선반에서 유휴 상태일 때 전력을 사용하지 않음.
  • 마운트되지 않은 영화를 선택하면 넣어야 할 바인더 슬롯, 디스크 번호 또는 볼륨 UUID를 정확히 안내함.
  • 마운트가 완료되면 StreamGate가 원시 블록 장치에서 HTTP 206 바이트 범위 요청으로 미디어를 스트리밍하므로, 기가바이트 단위 데이터를 SSD에 압축 해제하거나 추출하지 않아도 됨.
  • 화면 안의 대화형 TMDb 검색으로 모호한 제목을 수정할 수 있으며, 이때 실제 선반 위치 정보는 보존됨.

아키텍처

  • 브라우저 클라이언트는 데스크톱·TV·태블릿에서 접속함.
  • 포트 5000의 HuskVault 오케스트레이터 구성은 다음과 같음.
  • index.html: 반응형 포스터 그리드, 마운트 모달, 설정 화면임.
  • server.py: /api/scan, /api/status, /api/fix_match REST API임.
  • scraper.py: 증분 TMDb 및 GuessIt 스크래퍼임.
  • catalog.json: 저장 티어와 선반 위치를 유지하는 마스터 색인임.
  • 포트 8080의 HuskHoard 커널 데몬은 실시간 볼륨 상태·UUID 매핑·활성 스트림을 제공하는 /api/dashboard와 블록 스토리지에서 HTTP 206 바이트 범위 스트리밍을 수행하는 /stream/<file> 경로로 구성됨.

빠른 시작

  • 사전 요구 사항은 최신 Linux 운영체제(Ubuntu 22.04/24.04, Debian 12, Arch), Python 3.10 이상, 기본 포트 8080에서 실행 중인 HuskHoard 데몬, 무료 TMDb API 키임.
  • 저장소를 복제하고 requests, guessit 의존성을 설치한 뒤 server.py를 실행함. 저장소 주소는 https://github.com/HuskHoard/HuskVault.git 임.
  • 서버는 http://localhost:5000 또는 http://YOUR_LAN_IP:5000에서 접속 가능함.
  • UI의 Settings에서 TMDb API v3 인증 키, Hot Tier Folder Path(/path/to/huskhoard/hot_tier), HuskHoard Daemon Endpoint(http://127.0.0.1:8080 또는 LAN IP)를 입력함.
  • Save Configuration을 누른 뒤 Scan Library를 선택해 라이브러리를 스캔함.

물리 미디어 작업 흐름

  • HuskVault는 볼륨 텔레메트리에 따라 다음 상태 배지를 표시함.
  • RESIDENT: Hot SSD Tier에 상주하며 즉시 스트리밍함.
  • ONLINE: Nearline 드라이브 또는 장착된 디스크에 있으며, 드라이브를 깨운 뒤 StreamGate로 즉시 스트리밍함.
  • OFFLINE: BD-R·M-DISC·테이프 등 콜드 선반에 있으며, 예를 들어 “Binder A · Disc #12를 넣어 주세요”라는 안내를 표시함.
  • 제목 매칭을 수정하려면 그리드 카드에 마우스를 올리고 왼쪽 위의 원형 아이콘을 누른 뒤, TMDb에서 제목으로 검색하거나 숫자형 TMDb ID를 입력함.
  • 포스터와 메타데이터는 즉시 갱신되며, 실제 물리 저장 위치는 보존됨.

지원 아카이브 미디어

  • 광학 미디어(BD-R, BD-RE, M-DISC): 아카이브를 표준 ISO 또는 원시 UDF 볼륨으로 기록할 수 있으며, 디스크 케이스에 라벨을 붙이면 HuskVault가 정확한 슬롯을 안내함.
  • LTO Ultrium 테이프: HuskHoard로 포맷한 LTO-5부터 LTO-9까지 기본 호환됨.
  • 회전이 멈춘 외장 하드 드라이브: USB 드라이브를 보호 케이스에 넣어 선반에 보관하고, 박스 세트를 시청할 때만 연결하는 방식임.

라이선스

  • HuskVault는 AGPL v3 라이선스에 따라 배포되는 오픈소스 소프트웨어임.
  • HuskHoard 스토리지 티어링 엔진과 함께 실행되도록 설계됨.