Mineradio 딥다이브
— 비트에 반응하는 시네마틱 음악 플레이어

사용자 선곡 → 서버 → 음원 URL

렌더러(UI)가 fetch('http://127.0.0.1:{port}/song_url?id=...')를 호출한다. 로컬 서버(server.js)가 이를 받아 NeteaseCloudMusicApi의 song_url_v1()을 호출하고, 저장된 로그인 쿠키를 함께 전송해 인증된 스트리밍 URL을 반환한다.

오디오 로딩 → BPM 분석

렌더러의 오디오 요소가 음원 URL을 로드한다. 동시에 music-tempo.min.js가 오디오 버퍼를 분석해 BPM과 비트 타임스탬프 배열을 생성한다. 이 데이터는 로컬 서버의 dj-analyzer.js에도 전달되어 킥 에너지맵과 카메라 비트 타임라인이 계산된다.

비트맵 → Three.js 이벤트

분석 결과인 beatmap이 렌더러로 반환된다. UI 루프는 requestAnimationFrame으로 현재 재생 시간을 비트맵과 대조한다. 킥 비트 도달 시 Three.js 파티클 시스템에 폭발 이벤트가 발생하고, 카메라 비트 도달 시 GSAP 타임라인이 카메라 위치를 부드럽게 이동시킨다.

가사 무대 동기화

서버에서 가져온 가사 타임스탬프와 오디오 재생 시간을 비교해 현재 가사 라인을 강조한다. 사용자가 설정한 발광 강도, 가사 위치, 각도 값이 실시간으로 CSS 변수와 Three.js 유니폼(uniform)으로 주입된다.

Electron: 웹 앱을 데스크탑 앱으로

Electron의 핵심 개념인 메인 프로세스 ↔ 렌더러 프로세스 분리를 실전 코드로 배울 수 있다. desktop/main.js는 app.requestSingleInstanceLock()으로 중복 실행을 방지하고, ipcMain.on()으로 렌더러의 요청을 처리한다. desktop/preload.js는 contextBridge를 사용해 렌더러에 안전하게 API를 노출하는 방법을 보여준다.

// 단일 인스턴스 잠금 패턴 (desktop/main.js)
const gotLock = app.requestSingleInstanceLock();
if (!gotLock) {
  app.quit();     // 이미 실행 중이면 즉시 종료
} else {
  app.on('second-instance', () => {
    mainWindow.focus();   // 기존 창에 포커스
  });
}

Three.js: 3D 파티클 시스템 설계

public/vendor/three.r128.min.js를 사용해 PointCloud (포인트 클라우드) 형태의 파티클 시스템을 구축하는 방법을 배울 수 있다. 핵심은 BufferGeometry에 position 배열을 동적으로 갱신하는 패턴이다. 카메라 무브먼트는 Three.js Camera의 position과 lookAt을 GSAP 트윈으로 보간해 구현한다.

3D 플레이리스트 선반(Shelf) 구현에서는 BoxGeometry·PlaneGeometry와 텍스처 맵핑, 마우스 Raycaster를 활용한 3D 클릭 감지를 배울 수 있다.

오디오 DSP: 바이쿼드 필터 직접 구현

dj-analyzer.js의 makeBiquad()와 runBiquad() 함수는 DSP (Digital Signal Processing, 디지털 신호 처리)의 가장 기초적인 필터를 JavaScript로 구현한 예시다. 수학 공식을 코드로 옮기는 과정과, 백분위수(percentile)를 이용해 에너지 임계값을 동적으로 설정하는 방법이 담겨 있다.

// 바이쿼드 하이패스 필터 계수 계산 (dj-analyzer.js)
function makeBiquad(type, freq, q, sr) {
  const w0 = 2 * Math.PI * freq / sr;  // 각주파수
  const alpha = Math.sin(w0) / (2 * q); // Q 팩터 기반 alpha
  // b0, b1, b2, a0, a1, a2 계수 계산 후 정규화
  return { b0, b1, b2, a1, a2, x1:0, x2:0, y1:0, y2:0 };
}

CSS 글래스모피즘: backdrop-filter 심화

Mineradio의 UI는 backdrop-filter: blur(34px) saturate(1.34)를 핵심으로 하는 글래스 효과를 광범위하게 사용한다. SVG 필터를 활용한 고성능 글래스 대안도 구현되어 있어, CSS backdrop-filter 지원이 약한 환경에서의 폴백 전략을 배울 수 있다.

CSS 변수(--glass-bg, --glass-border, --glass-shadow)를 시스템처럼 설계해 테마 전환이 변수 값 하나로 전파되는 구조도 주목할 만하다.

Node.js 로컬 서버 + 외부 API 프록시 패턴

server.js는 Electron 앱에서 외부 API를 안전하게 사용하는 패턴의 교과서다. 로그인 쿠키를 파일에 저장하고(.cookie, .qq-cookie), 모든 인증이 필요한 API 호출에 쿠키를 자동으로 주입한다. QQ 음악처럼 직접 접근이 어려운 서비스의 쿠키를 BrowserWindow로 별도 세션(partition)에 로그인해서 추출하는 방법도 배울 수 있다.

GSAP + CSS 애니메이션 시퀀스 설계

스플래시 화면에서 "Mine"과 "radio" 두 글자가 필름 컷처럼 등장하는 애니메이션은 순수 CSS @keyframes로 구현되어 있다. clip-path: inset()으로 글자를 수직 방향으로 슬라이드인시키고, skewX·scaleX로 속도감을 더하는 고급 CSS 기법이 담겨 있다. GSAP은 실제 재생 중 카메라·파티클 인터랙션에 사용되어, CSS 애니메이션과 JS 애니메이션을 역할에 따라 구분하는 설계 전략을 보여준다.

로컬에서 개발 환경 실행하기 난이도 ★☆☆ 입문

소스를 클론하고 npm install 후 npm start로 Electron 앱을 띄워보자. 어떤 창이 열리고, 개발자 도구(F12)에서 어떤 오류가 나타나는지 확인한다. desktop/main.js를 열어 GPU 가속 스위치 목록을 읽고, 각 스위치의 역할을 Chromium 공식 문서에서 찾아보는 것도 좋다.

git clone https://github.com/XxHuberrr/Mineradio
cd Mineradio
npm install
npm start

바이쿼드 필터 시각화 도구 만들기 난이도 ★★☆ 중급

dj-analyzer.js의 makeBiquad()·runBiquad() 함수를 이해하고, 간단한 HTML 페이지에서 Web Audio API의 AnalyserNode와 결합해 실시간 주파수 스펙트럼을 Canvas로 그려보자. 로우패스(저음역)와 하이패스(고음역) 필터를 분리해 각각 다른 색으로 표시하면 DSP 개념이 눈에 보인다.

날씨 기반 배경색 변경 기능 구현 난이도 ★★☆ 중급

server.js의 Open-Meteo 날씨 API 코드를 읽고, 날씨 조건(맑음·흐림·비·눈)에 따라 배경 그라디언트 색상이 달라지는 간단한 HTML 페이지를 만들어보자. Mineradio의 날씨 라디오 로직이 어떻게 작동하는지 이해하는 데 도움이 된다.

// Open-Meteo API 호출 예시 (현재 위치 날씨)
const res = await fetch(
  'https://api.open-meteo.com/v1/forecast' +
  '?latitude=37.5&longitude=127.0' +
  '&current_weather=true'
);
const data = await res.json();
console.log(data.current_weather.weathercode);

최소 Electron + Three.js 파티클 앱 만들기 난이도 ★★★ 고급

Mineradio의 아키텍처를 참고해 최소한의 Electron 앱에 Three.js 파티클을 넣어보자. 목표: (1) main.js에서 BrowserWindow를 열고, (2) index.html에서 Three.js로 1000개 파티클을 띄우고, (3) 마우스 X 좌표에 따라 카메라가 회전하는 인터랙션을 추가한다. Mineradio의 코드 구조를 참고하되, 처음부터 직접 작성해보는 것이 핵심이다.

비트 감지 → DOM 반응 시각화 난이도 ★★★ 고급

Web Audio API로 음악 파일을 로드하고, dj-analyzer.js의 바이쿼드 필터 로직을 참고해 저음역 에너지가 임계값을 넘을 때 화면의 배경색이 순간적으로 변하는 페이지를 만들어보자. 이 실습을 마치면 Mineradio의 파티클 폭발 메커니즘을 정확히 이해하게 된다.