Streambert — Electron으로
만든 광고 제로 스트리머

먼저, "Electron 데스크탑 앱"이 뭔가?

왜 웹 브라우저가 아니라 데스크탑 앱으로 만드는가.

VS Code, Slack, Discord, Figma 데스크탑 — 우리가 매일 쓰는 데스크탑 앱 상당수가 사실은 Chromium 브라우저 + Node.js로 만들어졌다. 이 조합을 묶어 데스크탑 앱처럼 보이게 해주는 프레임워크가 Electron이다. 웹 기술(HTML/CSS/JS)을 쓰면서도 파일 시스템 접근, OS API, 시스템 트레이, 알림 같은 네이티브 기능을 쓸 수 있다.

Streambert는 영화·드라마·애니메이션을 외부 스트리밍 제공자에서 끌어와 재생하는 데스크탑 앱이다. 핵심은 광고와 추적기를 네트워크 레벨에서 100% 차단하면서 m3u8 스트림만 통과시키는 미들웨어 구조다. 이 한 가지를 위해 Electron의 모든 기능 — Session, webRequest, BrowserWindow, IPC — 을 본격적으로 활용한다.

이 프로젝트의 핵심 메시지

한 문장으로 줄이면.

TrendShift 25위 안에 든 이유

차별점 + 경쟁 우위.

차별점 다섯 가지

• 광고/추적기 100% 차단 — 단순 도메인 차단이 아니라 session.webRequest.onBeforeRequest로 네트워크 레벨 차단 + 통계 시각화까지 제공.
• 크로스플랫폼 패키징 — Windows(.exe NSIS), macOS(.dmg), Linux(.deb/.AppImage/.rpm/.pacman) 6가지 형식을 electron-builder 하나로 빌드.
• 책임 분리가 깔끔한 IPC 구조 — storage·downloads·subtitles·allmanga·player·blockStats 6개 IPC 모듈로 분리.
• m3u8 가로채기 + 다운로드 위임 — 메인 프로세스가 네트워크에서 m3u8/vtt URL을 추출해 렌더러에 전달, 다운로드는 외부 CLI(vid-dl-cli-only)에 넘김 (관심사 분리).
• 메모리 관리 진심 — V8 힙을 256MB로 캡, 수동 GC, 셰이더 캐시 플러시, 렌더러 프로세스 수 제한 — 데스크탑 앱 메모리 누수에 정면 대응.

경쟁 비교 — 웹브라우저 vs Streambert

전체 기술 지도

메인 · 렌더러 · 외부 API · 패키징.

메인 프로세스 (Electron / Node.js)

렌더러 (Frontend)

외부 API · 데이터 소스

인프라 · 패키징 형식

시스템 구조와 6가지 설계 패턴

전체 구조도 → 핵심 패턴 하나하나.

시스템 구조도

┌────────────────────────────────────────────────────────────────────┐
│                       사용자 데스크탑                                │
│                                                                    │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │                    Electron 앱 (Streambert)                    │  │
│  │                                                              │  │
│  │  ┌─────────────────────┐      ┌──────────────────────────┐  │  │
│  │  │  MAIN PROCESS       │ IPC  │  RENDERER (React)        │  │  │
│  │  │  index.js           │◄────►│  src/App.jsx             │  │  │
│  │  │                     │      │  + pages, components     │  │  │
│  │  │  - BrowserWindow    │      │  - HomePage              │  │  │
│  │  │  - Session 제어      │      │  - MoviePage / TVPage    │  │  │
│  │  │  - IPC 핸들러:        │      │  - LibraryPage           │  │  │
│  │  │    · storage         │      │  - SettingsPage          │  │  │
│  │  │    · downloads       │      │  - DownloadsPage         │  │  │
│  │  │    · subtitles       │      │                          │  │  │
│  │  │    · allmanga        │      │  ┌────────────────────┐ │  │  │
│  │  │    · player          │      │  │ <webview>          │ │  │  │
│  │  │    · blockStats      │      │  │ persist:player     │ │  │  │
│  │  │  - 광고 차단 미들웨어  │      │  │ (VidSrc 임베드)     │ │  │  │
│  │  └─────────┬───────────┘      │  └────────────────────┘ │  │  │
│  │            │                  └──────────────────────────┘  │  │
│  │            ▼                                                │  │
│  │      preload.js (contextBridge)                              │  │
│  └──────────────────────────────────────────────────────────────┘  │
│              ▲                            ▲                        │
│              │ HTTPS/메타데이터              │ HTTPS/m3u8 스트림      │
│              ▼                            ▼                        │
│  ┌─────────────────────┐         ┌──────────────────────────────┐  │
│  │  TMDB / AniList     │         │  VidSrc / AllManga.to /      │  │
│  │  (메타데이터)         │         │  videasy.net / 2Embed         │  │
│  └─────────────────────┘         └──────────────────────────────┘  │
│                                                                    │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  외부 CLI 의존성: vid-dl-cli-only + ffmpeg (다운로드 시)        │   │
│  └─────────────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────────────┘

패턴 1 — 3-Process Electron 모델

Electron은 한 앱 안에 세 가지 종류의 프로세스가 동시에 돈다. 각자 역할이 다르고, 메모리도 공유하지 않는다.

패턴 2 — Session Partitioning (세션 분리)

Streambert는 한 앱 안에서 3개의 분리된 Electron 세션을 운영한다. 각 세션은 독립된 쿠키 저장소·캐시·권한을 가진다.

// index.js 발췌
const playerSession  = session.fromPartition("persist:player");   // 영화/시리즈 재생용
const trailerSession = session.fromPartition("persist:trailer");  // 예고편 재생용
const redeemSession  = session.fromPartition("partition:wyzie-redeem"); // 자막 키 (비영구)

왜 분리하나? 플레이어 세션엔 광고 차단 + m3u8 가로채기를 강하게 걸고, 트레일러 세션엔 가벼운 차단만 건다. 자막 발급 세션은 partition: 접두사(persist: 없음)로 영구 저장하지 않아 보안에 유리하다.

패턴 3 — webRequest 미들웨어 (광고 차단)

const BLOCKED_HOSTS = [
  "*://www.google-analytics.com/*",
  "*://googletagmanager.com/*",
  "*://doubleclick.net/*",
  // ... 50여 개의 광고/추적기 도메인
];

playerSession.webRequest.onBeforeRequest(
  { urls: [...BLOCKED_HOSTS, ...MEDIA_URLS] },
  (details, callback) => {
    const { url } = details;
    const isMedia = url.includes(".m3u8") || url.includes(".vtt");
    if (!isMedia) {
      blockStats.recordBlockedRequest(url);  // 통계 기록
      callback({ cancel: true });              // 요청 취소!
      return;
    }
    // 미디어 URL은 통과 + 렌더러에 알림
    mainWindow.webContents.send("m3u8-found", url);
    callback({});  // 요청 허용
  }
);

패턴 4 — IPC 모듈 분리

index.js가 통째로 길어지지 않도록, IPC 핸들러를 도메인별 모듈로 쪼갰다. 각 모듈은 register() 함수를 export하고, index.js는 그냥 호출만 한다.

src/ipc/
├── allmanga.js     ← 애니 스크레이퍼 (AllManga.to)
├── blockStats.js   ← 광고 차단 통계 저장/조회
├── downloads.js    ← 다운로드 큐, 외부 CLI 호출
├── player.js       ← 플레이어 제어 (mute, fullscreen)
├── storage.js      ← TMDB 키, 설정, 시크릿 마이그레이션
└── subtitles.js    ← 자막 다운로드 (Wyzie)

storageIpc.register();
downloadsIpc.register(getMainWindow);
subtitlesIpc.register({ getDownloads, saveDownloads });
allmangaIpc.register();
playerIpc.register(getMainWindow, { writeSecretMigration });
blockStats.init(getMainWindow);

패턴 5 — Picture-in-Picture (Pop-Out 창)

영상을 작은 별도 창으로 띄우는 PiP 기능. 새 BrowserWindow를 만들고 alwaysOnTop: true로 설정하되, 같은 세션 파티션을 공유해 광고 차단 규칙이 자동 적용된다.

pipWindow = new BrowserWindow({
  width: 640, height: 360,
  minWidth: 320, minHeight: 180,
  alwaysOnTop: true,           // 다른 창 위에 항상 표시
  webPreferences: {
    partition: "persist:player",  // 같은 세션 공유 → 광고 차단 그대로
    contextIsolation: true,
    nodeIntegration: false,
    preload: "popout-preload.js"
  }
});

패턴 6 — 메모리 관리 (V8 캡 + 명시적 정리)

장시간 재생 시 메모리가 쌓이지 않게 적극적으로 관리한다. Electron 앱이 부풀어 오르는 흔한 문제를 정면 대응.

1. V8 힙 캡 — --max-old-space-size=256으로 OldGen 힙을 256MB로 제한
2. 렌더러 수 제한 — --renderer-process-limit=3으로 동시에 3개까지만
3. 디스크 캐시 캡 — --disk-cache-size=80MB
4. player-stopped 시 정리 — 추적 중인 webContents.destroy() → 캐시 플러시 → 수동 GC 호출

// player-stopped 이벤트 처리 (영상 페이지 unmount 시 발생)
ipcMain.on("player-stopped", () => {
  // 1) 추적 중인 player webContents 모두 destroy
  for (const id of playerWcIds) {
    const wc = webContents.fromId(id);
    if (wc && !wc.isDestroyed()) {
      wc.setAudioMuted(true);
      wc.destroy();
    }
  }
  // 2) 플레이어 세션 캐시 플러시
  const ps = session.fromPartition("persist:player");
  ps.clearCache();
  ps.clearStorageData({ storages: ["shadercache", "cachestorage"] });
  // 3) GC 힌트 (메인 + 렌더러)
  if (typeof global.gc === "function") global.gc();
});

레포 구조 해부

어디에 뭐가 있는지.

streambert/
├── index.js                  # 핵심 Main process 엔트리 (창 생성, 광고 차단, IPC 등록)
├── preload.js                # 메인 창용 contextBridge (화이트리스트 API)
├── popout-preload.js         # PiP 창용 별도 preload (타이틀바 컨트롤만 노출)
├── index.html                # Vite 빌드 진입 HTML
├── vite.config.js            # Vite 설정 (React 플러그인 등)
├── package.json              # 의존성 + electron-builder 설정
├── tmdb-tutorial.md          # 사용자 가이드: TMDB API 키 발급
│
├── public/                   # 정적 자산 (아이콘, 설치 사이드바)
│   ├── icon.png
│   ├── installer-sidebar.bmp # NSIS 설치 마법사 좌측 이미지
│   ├── logo.svg
│   └── sized/                # Linux용 다해상도 아이콘
│
├── src/                      # 렌더러 소스
│   ├── main.jsx              # React 진입점 (createRoot)
│   ├── App.jsx               # 라우팅 + 전역 상태
│   │
│   ├── components/           # 재사용 컴포넌트
│   │   ├── Sidebar.jsx
│   │   ├── MediaCard.jsx
│   │   ├── SetupScreen.jsx        # 최초 실행 시 TMDB 키 입력
│   │   ├── SearchModal.jsx
│   │   ├── DownloadModal.jsx
│   │   ├── SubtitleDownloaderModal.jsx
│   │   ├── TrailerModal.jsx       # YouTube 트레일러 (별도 세션)
│   │   ├── TrendingCarousel.jsx
│   │   ├── ErrorBoundary.jsx
│   │   ├── KeyboardShortcutsModal.jsx
│   │   ├── BlockedStatsModal.jsx  # 광고 차단 통계 시각화
│   │   ├── UpdateModal.jsx
│   │   ├── CloseConfirmModal.jsx  # 다운로드 중 종료 확인
│   │   ├── WindowTitlebar.jsx     # 커스텀 타이틀바
│   │   └── Icons.jsx
│   │
│   ├── pages/                # 라우트 단위 페이지
│   │   ├── HomePage.jsx
│   │   ├── MoviePage.jsx
│   │   ├── TVPage.jsx
│   │   ├── DownloadsPage.jsx
│   │   ├── LibraryPage.jsx        # 시청 기록, 위시리스트
│   │   └── SettingsPage.jsx
│   │
│   ├── ipc/                  # 메인 프로세스 IPC 모듈
│   │   ├── allmanga.js
│   │   ├── blockStats.js
│   │   ├── downloads.js
│   │   ├── player.js
│   │   ├── storage.js
│   │   └── subtitles.js
│   │
│   ├── styles/
│   │   ├── global.css
│   │   └── fonts/            # Bebas Neue, DM Sans (로컬 호스팅, asarUnpack 예외)
│   │
│   └── utils/                # 렌더러 유틸
│       ├── api.js            # TMDB API 호출 래퍼
│       ├── storage.js        # localStorage 추상화
│       ├── subtitles.js
│       ├── updates.js        # 앱 자동 업데이트 체크
│       ├── backup.js         # 스케줄 백업
│       ├── ageRating.js
│       ├── aniSkip.js        # 애니 오프닝/엔딩 스킵 정보
│       ├── episodeMappings.js
│       ├── homeLayout.js
│       ├── appearance.js     # 테마/UI 설정
│       ├── useBlockedStats.js  # React hook
│       └── useRatings.js       # React hook
│
├── screenshots/              # README 이미지들
├── .github/                  # GitHub Actions, 이슈 템플릿
├── .gitignore
└── LICENSE                   # GPL-3.0

분야별 배울 것

기술 영역마다 무엇을 가져갈지.

Electron 기초 + 보안 모델

IPC (Inter-Process Communication)

네트워크 가로채기 (webRequest)

Session Partitioning

React + Vite 데스크탑

HLS / m3u8 스트리밍

크로스플랫폼 패키징

메모리 / 성능

하드웨어·시스템 요구사항

개발용 vs 사용자용.

직접 해볼 수 있는 9단계

난이도별 실습 — Easy → Hard.

실습 1 — Electron 빈 창 띄우기Easy

실습 2 — preload로 안전한 API 노출Easy

실습 3 — Streambert 클론 후 직접 빌드Easy

실습 4 — 광고 차단 도메인 차단기 만들기Medium

실습 5 — React + Vite + Electron 보일러플레이트Medium

실습 6 — IPC 모듈 패턴 적용Medium

실습 7 — 크로스플랫폼 빌드 파이프라인Hard

실습 8 — m3u8 다운로더 직접 구현Hard

실습 9 — 자동 업데이트 + 코드사이닝Hard

4주 코스 — "Electron 데스크탑 개발자 되기"

주차별로 따라가면 전체 스택 체득.

주변 기술까지 넓히기

• Tauri — Electron의 경량 대안 (Rust 백엔드). Streambert를 Tauri로 마이그레이션한다면? 비교 학습.
• HLS.js — 브라우저에서 직접 m3u8 재생. webview 대신 native <video>로 처리하는 길.
• ffmpeg.wasm — 외부 CLI 없이 브라우저 내에서 영상 변환.
• Content Security Policy — Streambert는 임베드 사이트의 CSP를 제거한다. 반대로 본인 앱의 CSP를 강하게 거는 법.
• SQLite (better-sqlite3) — Streambert는 JSON 파일에 시청 기록을 저장. 라이브러리 규모가 커지면 임베디드 DB가 어울린다.

핵심 용어 한눈에

자주 마주칠 단어들.

더 깊이 파고들 자료

공식 · Electron 학습 · 관련 라이브러리.

공식 자료

• GitHub — truelockmc/streambert
• TrendShift — Streambert 페이지
• vid-dl-cli-only (Streambert가 사용하는 다운로더)

Electron 학습

• Electron 공식 문서
• Electron Security Checklist
• electron-builder 공식 문서
• NSIS

프론트엔드 · 미디어 라이브러리

• Vite 공식 문서
• TMDB API 문서
• AniList API 문서
• HLS.js (브라우저 HLS 재생)
• FFmpeg