tiklive는 틱톡 라이브 스트리밍을 연결하는 오픈소스 도구이자 이벤트 서버다. 틱톡 라이브의 웹소켓(WebSocket) 데이터를 유형이 지정된 JSON 이벤트로 바꿔 채팅, 선물, 좋아요, 팔로우, 공유, 입장, 구독, 시청자 수를 스트리밍 오버레이에 전달한다. 브라우저 클라이언트, 채팅·알림·목표 막대 오버레이, 대시보드와 데모 모드도 제공한다. 방송을 켜지 않고도 오버레이를 만들 수 있으며, 브라우저에서 코드를 작성하지 않고 이벤트에 소리, GIF, 동영상, 음성 합성, OBS 장면 전환을 연결할 수 있다.

macOS 및 Windows용 데스크톱 앱을 내려받거나 npx tiklive로 실행할 수 있다.

틱톡 로그인이나 제삼자 서명 서비스, 헤드리스 브라우저를 사용하지 않는다. tiklive는 익명 ttwid 쿠키를 사용해 tiktok.com에 일반 HTTPS 요청을 보낸다. 스트림을 관찰하는 읽기 전용 도구라 채팅 메시지를 보내거나 방송에 직접 개입할 수 없다. 서버는 기본적으로 127.0.0.1에 바인딩되므로 데이터가 사용자의 컴퓨터 밖으로 나가지 않도록 구성된다. MIT 라이선스로 배포한다.

다만 공식 API가 아니라 틱톡의 비공개 웹 프로토콜을 사용한다. 틱톡이 프로토콜을 언제든 바꿀 수 있으므로 사용 목적에 맞게 틱톡 서비스 약관을 확인해야 한다.

설치 방법은 데스크톱 앱과 명령줄 실행, 라이브러리 이용으로 나뉜다. 데스크톱 앱은 GitHub Releases에서 받을 수 있다. 앱은 127.0.0.1:8080에서 서버를 실행하고 대시보드를 표시하며 자체 업데이트를 지원한다. macOS에는 Apple Silicon용과 Intel용 DMG가 있고, Windows에는 x64 설치 프로그램이 있다. Windows 앱은 아직 코드 서명을 받지 않아 처음 실행할 때 SmartScreen 경고가 표시된다. 이 경우 More info를 누른 다음 Run anyway를 선택한다. 자세한 내용은 데스크톱 앱 안내를 참고하면 된다.

명령줄 실행에는 Node 22 이상 또는 Bun이 필요하다.

text
npx tiklive # or: bunx tiklive

실행한 뒤 http://127.0.0.1:8080/에서 대시보드를 연다. 가짜 이벤트를 받으려면 사용자 이름에 demo를 입력한다. 옵션은 서버 안내에 정리돼 있다.

라이브러리로 설치할 때는 다음 명령을 사용한다.

text
npm install tiklive effect

라이브러리 진입점에서 effect는 동료 의존성(peer dependency)이다. 자세한 내용은 라이브러리 안내를 확인할 수 있다.

OBS 오버레이를 설정하려면 데스크톱 앱이나 npx tiklive로 tiklive를 실행하고, 대시보드에서 틱톡 사용자 이름을 입력한다. 해당 스트리머가 라이브 중이면 tiklive가 연결한다. OBS에서 브라우저 소스를 추가한 뒤 아래 URL 중 하나를 붙여 넣는다.

  • 채팅: http://127.0.0.1:8080/overlays/chat.html?username=NAME
  • 알림: http://127.0.0.1:8080/overlays/alerts.html?username=NAME
  • 목표 막대: http://127.0.0.1:8080/overlays/goal.html?username=NAME&metric=likes&target=10000

서버를 --token 옵션으로 실행했다면 URL에 &token=…을 추가한다. 가짜 이벤트로 시험할 때는 username=demo를 사용한다. 모든 오버레이 옵션은 오버레이 안내에 있다.

라이브러리는 목적에 따라 하위 경로를 제공한다.

가져오기 경로기능
tiklive서버: Server.layer, SessionManager, Session, routes
tiklive/nodeNode HTTP 서버에서 실행하는 서버: layer, runMain
tiklive/bunBun HTTP 서버에서 실행하는 서버: layer, runMain
tiklive/core틱톡 연결 기능: LiveConnection, TikTokWeb, 오류, demoEvents
tiklive/client브라우저, Bun, Node에서 쓰는 TikLive 클라이언트. 런타임 의존성 없음
tiklive/contracts이벤트·프로토콜 스키마와 유형
tiklive/testing테스트용 가짜 객체: 스크립트 가능한 소켓, 방 조회, 프레임 빌더
tiklive/tiklive.js/tiklive.js에서 제공하는 브라우저 클라이언트 번들

Effect 프로그램에서 틱톡 라이브에 연결하는 예시는 다음과 같다.

js
import { LiveConnection } from "tiklive/core";
import { Effect, Stream } from "effect";

LiveConnection.events("someone").pipe(
 Stream.runForEach((e) => Effect.log(e.type, e.timestamp)),
 Effect.provide(LiveConnection.layer()),
 Effect.runPromise,
);

Node나 Bun에서 실행 중인 서버를 구독하는 예시는 다음과 같다.

js
import { TikLive } from "tiklive/client";

const live = new TikLive({ username: "demo", server: "ws://127.0.0.1:8080/ws" });
live.on("gift", (e) => {
 if (!e.streaking) console.log(`${e.user.nickname} sent ${e.repeatCount}× ${e.giftName}`);
});

각 하위 경로에 대한 설명은 라이브러리 안내, 서버를 프로그램에 포함하는 방법은 서버 안내에서 볼 수 있다.

tiklive는 연결이 끊겼다가 다시 연결될 때 이어받기 커서가 없어 이벤트를 놓칠 수 있다. 메시지 ID를 기준으로 중복 이벤트를 제거한다. VPN이나 데이터센터 IP를 사용하면 틱톡이 연결을 거부할 수 있다.

서버는 기본값인 127.0.0.1에서 실행하거나 외부에 공개하기 전에 --token을 설정해야 한다. --allow-no-token을 전달하지 않는 한 토큰 없이 로컬호스트 밖에서 수신하도록 서버를 실행할 수 없다. tiklive CLI는 이 조건을 강제한다. Server.layer로 서버를 포함하는 경우에는 사용자가 token과 allowedHosts를 직접 설정해야 한다.

문서의 시작점은 문서 안내다. 여기에는 서버 실행(명령줄 옵션, 스트리머 감시, 토큰, 보안, 서버 포함), 오버레이(OBS 설정과 기본 오버레이), 액션(시청자 반응에 따른 소리·GIF·음성 재생과 OBS 장면 전환), 시청자 포인트(채팅·선물·좋아요·팔로우에 따른 포인트와 순위표), 라이브러리(연결 기능, 클라이언트, 계약, 테스트용 가짜 객체, 이벤트), 데스크톱 앱(설치, 업데이트, 첫 실행), 통신 프로토콜(웹소켓 메시지, REST 엔드포인트, 이벤트 유형), 아키텍처(패키지, 데이터 흐름, 설계 노트), 릴리스 절차(변경 세트, 릴리스, 서명—관리자용), 기여 안내와 AGENTS.md(저장소 구조와 규칙)가 포함된다.

소스에서 빌드하려면 package.json에 고정된 Bun 1.4.3이 필요하다.

text
bun install
bun run dev # builds the client, serves the overlays at http://127.0.0.1:8080
bun run desktop:dev # runs the desktop app from the checkout

bun run dev는 소스가 바뀌면 서버를 다시 불러온다. 감시 기능 없이 실행하려면 bun run start를 사용한다. 검사, 테스트와 작업 흐름은 기여 안내에 설명돼 있다. 라이선스는 MIT이며 저작권 표기는 Copyright 2026 Talkabout Design LLC다.