ctv-run

React, Vue 등 웹 기술로 만든 TV 앱을 Vizio, LG webOS, Fire TV, Samsung Tizen에 배포하고 실행하는 CLI 도구입니다.

스마트 TV 플랫폼마다 다른 개발 환경 구축과 앱 실행 과정을 단일 명령어로 자동화합니다.

🗂 목차

1. 실행 모드 개요
2. ctv.config.json
3. 플랫폼별 사전 준비
4. 플랫폼별 사용법
5. 주의사항

실행 모드 개요

플랫폼은 두 가지 모드를 지원합니다.

| 모드 | 옵션 | 설명 | |------|------|----------------------------------------| | Live Mode | (기본값) | TV가 로드할 URL을 TV에 주입. HMR 지원 (Tizen 제외) | | Static Mode | --target=dist | 빌드 결과물을 TV에 직접 설치 (Vizio 제외) |

Vizio는 구조상 항상 URL이 필요하므로 Live Mode만 지원합니다.

Tizen Live Mode는 HMR을 지원하지 않습니다. Samsung Tizen TV의 구형 WebKit이 ES native modules(type="module")를 지원하지 않아 vite dev 서버에 접속하면 검은 화면이 나타납니다. vite preview --host를 사용하세요.

ctv.config.json

프로젝트 루트에 생성하면 CLI 옵션을 생략할 수 있습니다. 사용하는 플랫폼의 설정만 추가하면 됩니다. CLI 옵션이 항상 우선합니다.

{
  "vizio": {
    "ip": "192.168.x.x",
    "url": "http://192.168.x.x:3300"
  },
  "fire": {
    "ip": "192.168.x.x",
    "android": {
      "package": "com.example.app",
      "projectPath": "/path/to/android-project"
    }
  },
  "tizen": {
    "ip": "192.168.x.x"
  },
  "webos": {
    "deviceName": "my-lg-tv"
  }
}

Fields

Vizio

| Field | 필수 | Description | |-------|------|-------------| | ip | ✅ | TV 로컬 IP | | url | | TV가 로드할 URL | | port | | TV가 로드할 URL의 포트 |

Fire TV

| Field | 필수 | Description | |-------|------|-------------| | ip | ✅ | TV 로컬 IP | | url | | TV가 로드할 URL | | port | | TV가 로드할 URL의 포트 | | android.package | ✅ | Android 앱 패키지명 | | android.activity | | 실행할 Activity (기본값: .MainActivity) | | android.projectPath | Static Mode 시 ✅ | Android 프로젝트 루트 경로 (gradlew가 있는 폴더) | | android.moduleName | | Android 모듈명 (기본값: app) | | android.adbPath | | adb 실행 경로 (기본값: adb) |

Tizen

| Field | 필수 | Description | |-------|------|-------------| | ip | ✅ | TV 로컬 IP | | url | | TV가 로드할 URL | | port | | TV가 로드할 URL의 포트 | | appId | | Tizen 앱 고유 ID (없으면 자동 생성) | | tizenPath | | tizen CLI 실행 경로 (기본값: tizen) | | sdbPath | | sdb 실행 경로 (기본값: sdb) | | configXmlPath | | 사용할 config.xml 경로 (우선순위: dist > 지정경로 > 루트 > 기본 생성) |

WebOS

| Field | 필수 | Description | |-------|------|-------------| | deviceName | ✅ | ares-cli에 등록된 기기 이름 | | url | | TV가 로드할 URL | | port | | TV가 로드할 URL의 포트 | | appId | | webOS 앱 ID (기본값: com.ctvrun.app) | | appInfoPath | | 사용할 appinfo.json 경로 (우선순위: dist > 지정경로 > 루트 > 기본 생성) |

Common

| Field | Description | |-------|-------------| | devServerPort | 모든 플랫폼에 공통으로 적용할 포트 (기본값: 3000) |

💡 TV IP가 개발자마다 다를 수 있으므로 ctv.config.json은 .gitignore에 추가하고, ctv.config.sample.json을 저장소에 공유하는 것을 권장합니다.

플랫폼별 사전 준비

Vizio

Playwright Chromium이 필요합니다.

npx playwright install chromium

Fire TV

ADB가 설치되어 있어야 하며, TV에서 개발자 옵션 → ADB 디버깅이 활성화되어 있어야 합니다.

# macOS — ADB 설치
brew install --cask android-platform-tools

# 연결 확인
adb devices

Static Mode(--target=dist) 사용 시 앱 코드에 다음 설정이 필요합니다.

AndroidManifest.xml

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<application android:usesCleartextTraffic="true" ...>

MainActivity.kt — ADB로 주입된 URL 처리

val intentUrl = intent.getStringExtra("TARGET_URL")

if (!intentUrl.isNullOrEmpty()) {
    webView.loadUrl(intentUrl)           // Live Mode
} else {
    webView.loadUrl("file:///android_asset/index.html")  // Static Mode
}

Tizen

Tizen Studio 설치 후 PATH를 설정하거나, ctv.config.json에 경로를 직접 지정합니다.

tizen CLI와 sdb는 Tizen Studio에 포함되어 있습니다. 별도 설치는 필요하지 않습니다.

방법 1 — PATH 설정

# ~/.zshrc 또는 ~/.bash_profile
export TIZEN_STUDIO_HOME="$HOME/tizen-studio"
export PATH="$PATH:$TIZEN_STUDIO_HOME/tools/ide/bin:$TIZEN_STUDIO_HOME/tools"

source ~/.zshrc

방법 2 — ctv.config.json에 경로 지정

{
  "tizen": {
    "tizenPath": "/home/user/tizen-studio/tools/ide/bin/tizen",
    "sdbPath": "/home/user/tizen-studio/tools/sdb"
  }
}

인증서 프로필이 없으면 첫 실행 시 자동으로 생성합니다.

WebOS

LG webOS CLI 설치 후 ares 명령어를 사용할 수 있습니다.

기기 등록은 ctv-run webos 첫 실행 시 자동으로 안내됩니다. 등록된 기기가 없으면 ares-setup-device를 대신 실행해줍니다.

플랫폼별 사용법 예시

Vizio

# URL 직접 지정
ctv-run vizio --ip=192.168.11.27 --url=http://192.168.11.10:3300

# 포트만 지정 → http://[내 PC IP]:3300 으로 자동 조합
ctv-run vizio --ip=192.168.11.27 --port=3300

작동 원리

Playwright로 Vizio 웹 런처를 자동 조작하여 페어링(PIN 입력) 후 앱 URL을 주입합니다.

Fire TV

# URL 직접 지정
ctv-run fire --url=http://192.168.11.10:3300

# 포트만 지정 → http://[내 PC IP]:3300 으로 자동 조합
ctv-run fire --port=3300

# Static Mode — dist를 Android assets에 복사 후 로컬 실행
ctv-run fire --target=dist

Static Mode는 androidAssetsPath 설정이 필수입니다.

작동 원리

• Live Mode: ADB로 앱을 실행하며 TARGET_URL extra를 주입합니다.
• Static Mode: dist 파일을 Android assets 폴더에 복사한 뒤 앱을 실행합니다. 앱은 file:///android_asset/index.html을 로드합니다.

Tizen

# URL 직접 지정
ctv-run tizen --ip=192.168.11.30 --url=http://192.168.11.10:3300

# 포트만 지정 → http://[내 PC IP]:3300 으로 자동 조합
ctv-run tizen --ip=192.168.11.30 --port=3300

# Static Mode — dist를 .wgt로 패키징하여 TV에 설치
ctv-run tizen --ip=192.168.11.30 --target=dist

작동 원리

• Live Mode: 개발 서버로 리다이렉트하는 index.html을 포함한 .wgt를 설치합니다.
• Static Mode: dist 폴더를 .wgt로 패키징하여 TV에 설치합니다.

config.xml이 없으면 자동 생성됩니다. 커스터마이징이 필요하면 프로젝트 루트에 config.xml을 추가하세요.

디버깅은 Chrome에서 http://[TV_IP]:9222로 접속합니다. (TV 설정에서 디버그 모드 활성화 필요)

WebOS

# URL 직접 지정
ctv-run webos --device=my-lg-tv --url=http://192.168.11.10:3300

# 포트만 지정 → http://[내 PC IP]:3300 으로 자동 조합
ctv-run webos --device=my-lg-tv --port=3300

# Static Mode — dist를 .ipk로 패키징하여 TV에 설치
ctv-run webos --device=my-lg-tv --target=dist

작동 원리

• Live Mode: 개발 서버로 리다이렉트하는 index.html을 포함한 .ipk를 설치합니다.
• Static Mode: dist 폴더를 .ipk로 패키징하여 TV에 설치합니다.

appinfo.json이 없으면 자동 생성됩니다.

주의사항

네트워크

개발 PC와 TV는 동일한 Wi-Fi 또는 유선 네트워크에 연결되어 있어야 합니다.

Live Mode 로딩 속도

Vite 개발 서버는 HMR을 위해 모듈을 개별 전송하므로 TV 사양에 따라 초기 로딩에 10~30초 이상 걸릴 수 있습니다. 성능 확인이 필요하다면 Static Mode를 사용하세요.

Tizen 포트 권한

ctv-run tizen 실행 시 권한 오류가 발생하면 sudo를 붙여 실행하세요.

sudo ctv-run tizen --ip=192.168.11.30