ASCILINE 딥다이브
— 영상을 "텍스트"로 스트리밍하는 실시간 ASCII 렌더링 엔진

1프로젝트 한줄 요약

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

ASCILINE은 실시간 비디오-ASCII 렌더링 엔진이다. 백엔드는 FastAPI + OpenCV + NumPy로 영상을 그리드(grid)로 다운샘플해 문자/색 버퍼를 만들고, 프론트엔드는 순수 Vanilla JS가 WebSocket으로 받은 프레임을 지터 버퍼(jitter buffer)에 쌓아 requestAnimationFrame 루프로 그린다. 오디오 트랙을 마스터 클럭(master clock)으로 삼아 A/V 동기를 맞추고, 정적/저움직임 프레임에는 적응형 코덱(adaptive codec)으로 변한 셀만 보내 대역폭을 수백 배 아낀다. 웹 UI 외에 터미널에서 트루컬러 ANSI로 직접 재생하는 모드(ascii_video_player2.py)도 함께 들어 있다.

2왜 주목받는가

"영상=텍스트"라는 발상이 푸는 네 가지 실전 문제.

단순히 "옛날 ASCII 무비 플레이어"였다면 트렌딩하지 못했을 것이다. ASCILINE이 주목받는 이유는 "영상의 실체를 텍스트로 바꾸면 생기는 부수효과"를 전면에 내세웠기 때문이다. README가 정리한 네 가지 "전략적 비전"은 그대로 차별점이 된다.

3기술 스택 전체 지도

백엔드(변환 엔진)·프론트엔드(렌더러)·코덱/인프라 각각.

① 백엔드 — 영상 디코딩 & 픽셀→문자 변환

백엔드의 일은 "영상 프레임을 그리드로 줄여 문자/색 버퍼로 만들고, WebSocket으로 밀어내는 것"이다. CPU 연산(리사이즈·인덱싱)이 핵심이라 NumPy 벡터화가 성능의 열쇠다.

② 프론트엔드 — Vanilla JS Canvas 렌더러

프레임워크가 전혀 없다(React·Vue 무관). app.js 한 파일이 WebSocket 수신·지터 버퍼·A/V 동기·Canvas 그리기를 다 한다. "장식 애니메이션 0, 순수 성능"이 코드 주석의 선언이다.

③ 코덱 · 인프라 · 보안

4아키텍처 심화 분석

영상 → 그리드 → 프레임 인코딩 → WS → Canvas, 그리고 A/V 동기.

전체 파이프라인 한눈에

입력은 MP4 한 개(또는 폴더/플레이리스트). 서버는 영상을 열어 폭(--cols)에 맞춰 그리드 크기(rows×cols)를 종횡비로 자동 계산하고, INIT 핸드셰이크로 FPS·모드·그리드를 클라이언트에 알린다. 이후 프레임마다 OpenCV로 읽어 NumPy로 문자/색 버퍼를 만들고, 적응형 코덱으로 인코딩해 WebSocket에 실어 보낸다. 동시에 /audio가 FFmpeg로 오디오를 스트림한다. 클라이언트는 프레임을 버퍼에 쌓고, 오디오 시계를 기준으로 정확한 타이밍에 Canvas에 그린다.

핵심 1 — 픽셀을 문자로: NumPy 벡터 매핑

변환의 심장은 "밝기값(0~255)을 문자 팔레트 인덱스로 바꾸는" 한 줄이다. AsciiMapper는 어두움→밝음 순으로 정렬된 92글자 팔레트를 들고, 파이썬 루프 없이 NumPy 인덱싱으로 그리드 전체를 한 번에 변환한다.

# 팔레트(어두움→밝음). 길이 n=93
PALETTE = " `.-':_,^=;><+!rc*/z?s ... %&@"   # 끝일수록 밝다

# gray: (rows, cols) uint8 밝기 행렬
indices = np.floor_divide(gray, max(1, 256 // n))  # 0..n-1 구간으로
np.clip(indices, 0, n - 1, out=indices)
char_codes = char_byte_lut[indices]   # 인덱스 → 문자코드, 통째로

# 색: BGR → RGB 후 양자화(상위 비트만 남김 → 압축률↑)
rgb = bgr_frame[:, :, ::-1]
if qb > 0: rgb = (rgb >> qb) << qb   # mode별 qb: 5→0, 4→2, 3→3, 2→5

# 셀당 4바이트 버퍼: [문자, R, G, B]
frame_buf[:, :, 0] = char_codes
frame_buf[:, :, 1:] = rgb

핵심 2 — 적응형 코덱: 프레임마다 최선의 인코딩 선택

원래 프로토콜은 매 프레임 그리드 전체를 다시 보냈다. codec.py의 encode_frame()은 프레임마다 바뀐 셀 비율(frac)을 재고, 세 인코딩 중 가장 작은 것을 골라 1바이트 태그로 표시한다. 똑똑한 점은 "양 극단의 명백한 패자는 시도조차 안 한다"는 것이다.

_DELTA_MAX_FRAC = 0.60   # 이보다 많이 바뀌면 DELTA는 손해 → 안 만듦
_ZLIB_MIN_FRAC  = 0.10   # 이보다 적게 바뀌면 전체 ZLIB는 손해

frac = changed.mean()              # 바뀐 셀 비율
candidates = []
if frac < _DELTA_MAX_FRAC:         # 적게 변함 → DELTA 후보
    candidates.append((TAG_DELTA, zlib(idx + vals), delta_shown))
if frac >= _ZLIB_MIN_FRAC or not candidates:
    candidates.append((TAG_ZLIB, zlib(raw), frame))

tag, payload, shown = min(candidates, key=lambda c: len(c[1]))  # 가장 작은 것
if len(raw) < len(payload):        # zlib이 오히려 부풀면 RAW로
    tag, payload, shown = TAG_RAW, raw, frame

핵심 3 — A/V 동기: 오디오가 절대 시계다

영상과 소리가 어긋나는(desync) 문제를 ASCILINE은 "오디오를 마스터 클럭으로 삼는다"는 한 원칙으로 푼다. 비디오 프레임은 각자 time = frameIndex / fps를 갖고 버퍼에 쌓이고, 렌더 루프는 오디오의 현재 재생 위치와 비교해 프레임을 버리거나 기다린다.

masterClock = (audio && !audio.paused)
  ? audio.currentTime               # 오디오가 절대 기준
  : (now - streamStartTime) / 1000; # 폴백: 벽시계

# 너무 뒤처진 프레임은 버리고 따라잡기(catch-up)
while (buf.length > 1 && buf[0].time < masterClock - 0.1) buf.shift();

# 아직 미래의 프레임이면 이번 틱은 대기
if (buf[0].time > masterClock + 0.05) return;

const frame = buf.shift().data;     # 지금 그릴 프레임

핵심 설계 패턴 요약

5디렉토리 구조 해부

파일 10여 개로 끝나는 단출한 단일 폴더 — 그래서 읽기 좋다.

6학습 포인트 (기술별)

실시간 스트리밍·코덱·Canvas 렌더링에서 무엇을 배우나.

A. NumPy 벡터화 — "루프를 지우면 빨라진다"

영상 한 프레임은 수만 개 픽셀이다. 이걸 파이썬 for로 돌면 실시간이 불가능하다. ASCILINE은 밝기→문자(floor_divide+LUT 인덱싱), 색 양자화((rgb>>qb)<<qb), 델타 비교(np.abs(a-b)>tol)를 모두 배열 통째 연산으로 처리한다. "파이썬 루프를 NumPy 연산으로 바꾸는" 사고법이 그대로 보이는 교본이다.

B. 적응형 코덱 — "상황마다 다른 압축을 고르기"

"무조건 zlib"이 정답이 아니다. 정지화면엔 델타가, 격변 프레임엔 전체 압축이 유리하다. ASCILINE은 바뀐 비율을 재서 후보를 만들고 가장 작은 걸 고른다. 게다가 "양 극단의 패자는 만들지도 않는" 가지치기로 CPU까지 아낀다. "정책을 데이터(프레임 특성)에 맡기는" 적응형 시스템 설계의 좋은 미니 사례다.

C. 크로스언어 byte-exact 테스트 — "보낸 것 = 받은 것" 증명

인코더(Python)와 디코더(JS)가 다른 언어면, "정말 똑같이 복원되나?"를 증명해야 한다. ASCILINE은 디코더 한 벌(codec.js)을 브라우저와 Node 테스트가 공유하고, Python이 만든 벡터를 Node가 풀어 바이트 단위 일치를 확인한다(check_vectors.js). "배포되는 코드가 곧 테스트되는 코드"라는 원칙은 그대로 베껴 쓸 가치가 있다.

D. 실시간 A/V 동기 — "시계를 하나로 정하라"

영상·음성이 따로 흐르면 반드시 어긋난다. 해법은 "무엇이 절대 시계인지 먼저 정하는 것"이다. ASCILINE은 오디오를 시계로 삼고, 비디오 프레임을 그 시계에 맞춰 버리거나(catch-up) 기다린다(wait). 시작 끊김은 "오디오 준비 게이트"로, 고FPS 부하는 grab() 데시메이션으로 푼다. 영상 플레이어·게임 루프·메트로놈 앱 어디에나 옮길 수 있는 원리다.

E. Canvas 위 "보이지 않는 선택 레이어"

Canvas에 그린 글자는 마우스로 드래그 선택이 안 된다(그림이니까). ASCILINE은 Canvas 위에 투명한 <pre>를 정확히 겹쳐(object-fit 위치까지 맞춤) 같은 텍스트를 깐다. 색은 transparent지만 DOM 텍스트라 선택·복사가 된다. "그래픽 위에 접근성/상호작용 레이어를 겹치는" 영리한 트릭이다.

7시스템 / 환경 요구사항

설치는 가볍지만, --cols 값이 곧 "하드웨어 부담 다이얼"이다.

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

난이도별 5단계 — 클론 후 본인 영상으로 바로 시도.

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

6주 코스 — NumPy 영상 처리부터 실시간 코덱·동기까지.

10핵심 키워드 사전

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

11참고 링크

• GitHub: YusufB5/ASCILINE
• 핵심 소스: stream_server.py(서버·WS) · app.js(렌더러) · codec.py/codec.js(적응형 코덱) · ascii_video_player2.py(엔진·터미널)
• 검증 스위트: experiments/ (gen_vectors · check_vectors · test_e2e · make_test_clips)
• 주요 의존성: FastAPI · NumPy · OpenCV · FFmpeg
• 배경 지식: MDN WebSocket · MDN Canvas API · DecompressionStream