# .env 파일에 PASSWORD 설정
echo

1. **VOD 소스 추가**: 설정 → 소스 관리 → VOD 소스 → API 추가를 선택하고 Apple CMS 수집 스테이션 주소(예: `https://example.com/api.php/provide/vod`)를 입력합니다. 상세 페이지 주소는 선택 사항입니다 (일부 소스는 플레이어 주소를 추출하기 위해 상세 페이지 크롤링이 필요함). 
2. **검색**: VOD 소스를 체크한 후 작품명을 입력하여 검색합니다. 검색은 서버 측에서 통합하며, 개별 소스의 실패가 전체 결과에 영향을 미치지 않습니다. 
3. **재생**: 상세 팝업창에서 에피소드를 선택하고 `/watch`로 진입합니다. 단축키(스페이스/←→/↑↓/F/Alt+←→)를 지원하며, 모바일에서는 길게 눌러 3배속 재생, 자동 연속 재생, 소스 변경 테스트 속도 측정 기능을 제공합니다. 시청/일시정지 시 이후 분할 파일이 자동으로 로컬에 캐싱됩니다 (설정에서 비활성화 가능). 플레이어 페이지에서 해당 에피소드를 「다운로드」하여(TS/MP4) 오프라인으로 시청할 수 있습니다. 
4. **진도 및 기록**: 이 장치의 IndexedDB에 자동 저장되며, 위치 정보만 데이터베이스에 기록하고 재생 시 최신 에피소드를 자동으로 동기화합니다. 
5. **설정 마이그레이션**: 설정 → 데이터 → 설정 가져오기/내보내기 (구 버전 LibreTV-Settings JSON의 기록 이관을 지원). 

## 라이브 / IPTV

1. **라이브 소스 추가**: 설정 → 소스 관리 → 라이브 소스 → M3U/M3U8 주소(선택 사항으로 XMLTV 프로그램 목록 주소)를 입력합니다. 추가 후 자동으로 활성화를 테스트하고 채널 수를 표시하며, 「소스 관리 → 데이터 소스 구독」에서도 VOD 소스와 함께 구독하여 가져올 수 있습니다. 배포자는 `DEFAULT_LIVE_SOURCES` 환경 변수를 사용하여 미리 설정할 수도 있습니다. 
2. **시청**: 「라이브」 페이지로 이동하여 그룹별 태그로 필터링하거나 채널을 검색한 후 클릭하면 바로 재생됩니다. HLS(m3u8)와 HTTP-FLV 두 가지 라이브 스트림을 지원하며, 직통 연결 실패 시 자동으로 프록시 경로를 통해 재시도합니다. 
3. **프로그램 목록**: 채널에 `tvg-id`가 포함되어 있고 구독 설정에 EPG 주소가 구성된 경우, 현재/다음 프로그램과 재생 진행 상황이 표시됩니다. 
4. **즐겨찾기 및 내보내기**: 채널을 즐겨찾기에 추가할 수 있으며, 구독 목록 전체를 표준 M3U 파일로 한 번에 내보내어 PotPlayer / VLC 등 외부 플레이어에서 사용할 수 있습니다. 

자세한 설명은 [라이브 / IPTV 문서](https://libretv.is-an.org/wiki/Live-IPTV.html)를 참조하십시오.

> ⚠️ 프로젝트는 어떠한 채널 소스도 내장하고 있지 않으며, 라이브 콘텐츠를 저장하거나 제작하지 않습니다. 오직 제3자의 공개 플레이리스트 분석 및 재생 기능만을 제공하며, 콘텐츠의 합법성은 해당 데이터 소스가 책임집니다. 내부 네트워크에서 자체 구축한 소스는 기본적으로 SSRF 방어에 의해 차단되며, 자체 배포자는 `LIVE_ALLOW_PRIVATE=1`을 명시적으로 설정하여 허용할 수 있습니다.

## 데이터 소스 구독 / 공유

data source(VOD 소스 + 라이브 소스)는 **JSON 파일로 내보내어 → 공개 URL에 호스팅한 후 → 다른 사용자가 「설정 → 소스 관리 → 데이터 소스 구독」에서 해당 URL을 입력하여 구독**할 수 있습니다. 

호스팅 주소에 특별한 요구 사항은 없으며, [npoint.io](https://www.npoint.io/)를 사용하여 JSON 파일을 무료로 호스팅할 수 있습니다(내용 붙여넣기만 하면 공개 URL이 생성됨). Gist, 객체 스토리지, 임의의 정적 호스팅 모두 사용 가능합니다.

### 구독 형식 (LibreTV-SourceList JSON)

```json
{

- **VOD(주문형 비디오) 소스**: `sites`에서 `type: 1`인 JSON 인터페이스(즉, Apple CMS 수집 사이트)를 가져옵니다. 일부 공유 설정은 `type`을 생략하거나 `0`으로 작성했지만, 주소가 `api.php/provide/vod`에 도달하면 여전히 가져옵니다. 사이트 자체에 `searchable: 0`(검색 불가)로 표시된 경우 건너뜁니다.
- **실시간 스트리밍(Live Stream) 소스**: `lives`에서 `type: 0`(또는 생략)인 M3U 재생 목록을 가져오며, `epg` 필드도 함께 가져옵니다. 일반 텍스트 채널 목록과 단일 컨테이너 JSON은 지원하지 않습니다.
- **Spider 유형 사이트는 건너뜁니다**: `type: 3`의 Spider(예: `csp_*` / `.jar` / `.js` / `.py`)는 TVBOX 자체의 Spider 엔진이 있어야 실행할 수 있으며, Node 측에서는 실행할 수 없습니다. XML 인터페이스나 외부 링크 JSON도 마찬가지입니다. 건너뛴 항목은 나머지 가져오기에 영향을 주지 않으며, 가져오기 결과는 "VOD 소스 8개 동기화됨, 라이브 소스 2개(TVBOX 설정); 사용 불가 항목 96개 건너뜀(Spider 엔진 92, XML 인터페이스 4)"와 같이 사실대로 표시됩니다.
- TVBOX 설정에는 수백 개의 사이트가 포함되는 경우가 많고 Spider 유형이 주를 이루므로, **몇 자릿수에서 열댓 개만 가져오는 것은 정상적인 현상**입니다.
- **형식 허용성**: 설정 내의 `//` 주석, 후행 쉼표(trailing comma), 문자열 내부의 이스케이프되지 않은 줄 바꿈은 자동으로 수정된 후에 파싱됩니다 (공유 설정에서 매우 흔하며, TVBOX 클라이언트가 사용하는 fastjson도 이러한 작성을 용인합니다).
- 기타 제한 사항: 구독 주소는 JSON을 직접 반환해야 합니다(Base64 / 압축 패키징된 공유 링크는 지원하지 않습니다). TVBOX의 "다중 컨테이너" 설정(최상위가 `urls` 배열)은 지원되지 않으므로, 단일 컨테이너 설정을 사용해 주십시오. 주소에 대한 공용 네트워크 검증, 중복 제거 및 수량 상한선은 위 형식과 완전히 일치합니다.

### 구독 동작 방식

- **구독**: 설정 → 소스 관리 → 데이터 소스 구독 → 구독 주소를 입력하고 「구독」을 누르면, 가져온 VOD 소스는 자동으로 체크되고 라이브 소스는 자동으로 활성화되며 모두 "구독됨" 표시가 붙고 항목에 "VOD N · Live M"이 표시됩니다.
- **동기화**: 구독 항목의 **⟳**를 수동으로 강제 동기화하면, 해당 구독명 아래의 VOD 소스와 라이브 소스가 전체적으로 대체됩니다.
- **관리 경계**: 구독 소스는 원격 목록을 기준으로 합니다. 개별 편집은 다음 동기화 시 덮어쓰여지며, 개별 제거는 재동기화 시 복원됩니다. 조정이 필요하면 원격 목록을 수정하거나 전체 구독을 직접 삭제하십시오. 구독을 삭제할 때 VOD 소스는 모두 제거됩니다. 라이브 소스는 **다중 귀속 공유** 방식입니다. 즉, 동일한 M3U가 여러 구독에서 참조될 수 있습니다(이름/EPG는 최초 가져오기를 기준으로 합니다). 구독을 삭제하거나 원격 목록에서 해당 소스를 제거한 후 동기화하더라도, 본 구독의 참조만 제외되며, 더 이상 어떤 구독에서도 참조되지 않을 때만 해당 소스가 완전히 제거됩니다. 수동으로 추가된 소스는 동기화에 영향을 받지 않으며, **즐겨찾는 채널은 항상 유지**됩니다.
- **내보내기 및 공유**: 설정 → 소스 관리 → 데이터 소스 구독 → 「데이터 소스 내보내기」를 통해 현재의 모든 VOD/라이브 소스(사전 설정 + 수동 + 구독, URL 기준 중복 제거)를 위의 JSON으로 내보낼 수 있습니다. 또는 「링크로 게시」를 사용하여 현재 **체크되고 활성화된** 소스를 한 번에 공개 클립보드(paste.rs, 실패 시 자동 0x0.st로 하향 조정)에 업로드할 수 있으며, 구독 창에 바로 붙여넣을 수 있는 URL이 반환되므로 자체 호스팅이 필요 없습니다. 주의: 게시된 내용은 **공개적으로 읽을 수** 있으며, 매번 새로운 링크가 생성되고 덮어쓰기 업데이트를 지원하지 않습니다. 장기간 안정적인 사용을 위해서는 내보내기 후 직접 호스팅하는 것을 권장합니다.

> 구독은 서버 측에서 가져옵니다(SSRF 검증 거침). 따라서 구독 주소에 CORS 설정이 필요 없습니다. 자세한 내용은 [데이터 소스 문서](https://libretv.is-an.org/wiki/Data-Sources.html)를 참조하십시오.

## 개발

```bash
npm install
PASSWORD=dev-password npm run dev   # http://localhost:8080
npm test                            # 핵심 라이브러리 단위 테스트 (cms-parser / m3u8 / ssrf)
...

npm version patch       # 또는 minor / major; package.json을 업데이트하고 git 태그를 지정합니다
git push && git push --tags