iptv-org/iptv 딥다이브
— 전 세계 1만 5천 개 방송 링크를 봇이 매일 점검·발행하는 거대 데이터 큐레이션 기계

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

iptv-org/iptv는 m3u 재생목록(playlist) 큐레이션 프로젝트다. 원천 데이터(채널 메타데이터)는 자매 레포 iptv-org/database에서, EPG(편성표)는 iptv-org/epg에서 가져온다. 이 레포가 책임지는 것은 "스트림 URL을 채널에 연결하고, 그 묶음을 국가·카테고리·언어·지역별 m3u로 발행하는 일"이다. 영상 자체는 저장하지 않으며, 라이선스도 데이터 공유에 어울리는 CC0(퍼블릭 도메인)다.

2왜 주목받는가

트렌딩 이유 · 다른 IPTV 목록 대비 장점.

인터넷에는 "IPTV m3u 목록"이 수없이 떠돈다. 그런데 대부분은 관리되지 않는 죽은 링크 덩어리이거나, 출처가 불분명한 불법 스트림을 섞어둔 것이다. iptv-org/iptv가 12만 스타를 모은 이유는 단순 "링크가 많아서"가 아니라, 데이터를 유지·검증·발행하는 엔지니어링이 진짜 오픈소스 프로젝트처럼 돌아가기 때문이다.

3기술 스택 전체 지도

데이터 처리 엔진(스크립트)·발행(GitHub Pages)·자동화(CI) 각각.

① 데이터 처리 엔진 (백엔드 = TypeScript CLI)

이 레포에는 "서버"가 없다. 대신 한 번 실행하고 끝나는 CLI 스크립트 묶음이 데이터를 가공한다. 전부 TypeScript이고, tsx로 컴파일 없이 바로 실행한다. 명령은 commander로 정의되고 package.json의 playlist:* 스크립트로 호출된다.

② 발행물 (프론트엔드 = 정적 m3u + README 표)

③ 자동화 · 인프라 (GitHub Actions)

4아키텍처 심화 분석

제보(이슈) → 봇 수집 → 검증 → 생성 → 발행, 데이터 큐레이션 파이프라인.

전체 흐름 한눈에

이 레포의 본질은 "한 방향으로 흐르는 데이터 컨베이어 벨트"다. 입력은 두 가지: ① 사람이 올린 GitHub 이슈(채널 추가/수정/신고), ② 자매 레포의 원천 데이터(channels·blocklist). 이걸 봇이 매일 빨아들여 내부 streams/*.m3u를 갱신하고, 검증을 통과하면 공개용 m3u를 새로 찍어 GitHub Pages와 API로 발행한다.

검증 게이트 — 데이터 품질을 코드로 강제

이 파이프라인의 심장은 validate.ts다. 단순히 "파일이 m3u 형식인가"를 넘어, 데이터의 의미적 정합성을 검사한다. 핵심 통찰은 오류(error)와 경고(warning)를 구분한다는 점이다 — error는 파이프라인을 멈추지만, warning은 흐름은 보내되 사람에게 알린다.

// 1) 모든 스트림을 url 키로 버퍼에 모아 "중복"을 감지
const buffer = new Dictionary<Stream>()
streams.forEach(s => { if (!selectedFiles.includes(s.filepath)) buffer.set(s.url, s) })

// 2) 검증 대상 스트림을 하나씩 게이트에 통과
if (buffer.has(stream.url))            log.add({ type:'error', ... })  // 중복
if (!isURI(stream.url))                log.add({ type:'error', ... })  // 잘못된 URL
if (!data.channelsKeyById.get(id))     log.add({ type:'warning', ... })// DB에 없음

// 3) 차단목록(블록리스트) 대조 — DMCA / NSFW
blocklistRecords.forEach(r => {
  if (r.reason === 'dmca')  log.add({ type:'error', ... })
  if (r.reason === 'nsfw')  log.add({ type:'error', ... })
})

핵심 설계 패턴

5디렉토리 구조 해부

데이터(streams)·엔진(scripts)·자동화(.github)의 3구역.

6학습 포인트

대규모 데이터 큐레이션 · CI 자동화에서 무엇을 배우나.

A. 사람-봇 분업 — "판단은 사람, 반복은 봇"

가장 큰 교훈은 기여의 진입장벽을 코드가 아니라 "양식"으로 낮춘 것이다. 기여자는 TypeScript를 몰라도 이슈 템플릿만 채우면 된다. 봇이 그걸 파싱해 데이터에 반영하고, 검증·정리·발행은 전부 자동이다. 커뮤니티 데이터 프로젝트를 키우는 핵심 설계다.

B. 검증을 CI 게이트로 강제하기

데이터가 깨지지 않게 지키는 비결은 "검증을 머지 조건으로 만드는 것"이다. check.yml은 PR에서 바뀐 파일만 골라 lint+validate를 돌리고, 실패하면 머지를 막는다. 사람의 선의에 기대지 않고 품질을 자동으로 집행한다. error/warning 구분, 외부 진실원(database·blocklist)과의 교차 검증도 그대로 배울 패턴이다.

C. cron + 봇 커밋으로 "살아 있는 데이터" 유지

update.yml의 cron: 0 0 * * * + GitHub App 토큰 + 봇 명의 커밋 조합은 "사람이 손대지 않아도 매일 스스로 갱신·발행되는 저장소"를 만든다. 모든 변경이 git 이력에 남아 추적·되돌리기가 된다(GitOps). 이건 데이터뿐 아니라 가격·환율·통계 같은 어떤 주기적 데이터에도 그대로 적용된다.

D. 하나의 모델, 여러 표현 (Generator 패턴)

같은 Stream 데이터에서 14종 generator가 국가·언어·카테고리·지역·도시별 m3u를, 또 export가 JSON을, readme:update가 마크다운 표를 찍어낸다. "데이터 모델과 출력 형식의 분리"가 명확해서, 새 분류 축을 추가하려면 generator 하나만 더 만들면 된다.

7시스템 / 환경 요구사항

쓰는 사람 vs 개발/기여하는 사람으로 나뉜다.

8직접 해볼 수 있는 실습 과제

난이도별 5단계 — 데이터 큐레이션·CI 자동화 체득.

9관련 기술 심화 학습 로드맵

6주 코스 — 데이터 포맷부터 CI 자동 발행까지.

10핵심 키워드 사전

본문·소스에 나온 용어 빠른 참조.

11참고 링크

• GitHub: iptv-org/iptv
• 전체 재생목록 표: PLAYLISTS.md · 기여 가이드: CONTRIBUTING.md
• 메인 재생목록: https://iptv-org.github.io/iptv/index.m3u
• 자매 레포 — 채널 DB: iptv-org/database · 편성표: iptv-org/epg · API: iptv-org/api
• 호환 플레이어/도구 모음: awesome-iptv
• 로컬 CI 실행 도구: nektos/act
• 법적 입장·저작권 클레임: 저장소 README의 Legal 섹션 및 copyright-claim 이슈 템플릿 참조