Streamlink

#!if code = "display: inline; padding: .125rem .25rem; background: #dddddd; border-radius: .25rem; font-size: .875rem; font-family: Cascadia Mono, Menlo, Monaco, Consolas, monospace"

#!if codeds = "display: inline; padding: .125rem .25rem; background: #383b40; border-radius: .25rem; font-size: .875rem; font-family: Cascadia Mono, Menlo, Monaco, Consolas, monospace"

<colbgcolor=#0073bd,#121657><colcolor=#ffffff,#ffffff> Streamlink 스트림링크
개발	Streamlink Community
최초 공개	2016년 9월 23일[1]
전신	Livestreamer
최신 버전	8.1.0 (2025년 12월 14일)
운영체제	Windows, macOS, Linux, BSD 등
종류	오픈 소스, CLI 프로그램, 스트리밍 유틸리티, Python 라이브러리
언어	Python (>=3.10)
라이선스	BSD 2-Clause Simplified License
관련 링크	| | PyPI

1. 개요

2. 역사

3. 주요 기능 및 특징

• 스트리밍 플랫폼 지원
  트위치, 유튜브, Kick을 비롯해 다양한 스트리밍 서비스 플러그인을 폭넓게 지원한다.
  커뮤니티 의견을 빠르게 반영해 플랫폼 변경에도 유연하게 대응한다.
• 스트림 추출 및 전송
  비디오와 오디오 데이터를 추출해 미디어 플레이어로 전송하거나 파일로 저장할 수 있다.
• 미디어 플레이어 연동
  VLC, MPlayer, mpv, 팟플레이어 등 다양한 미디어 플레이어와 연동된다.
• 스트리밍 프로토콜 호환성
  HLS, MPEG-DASH 등 현대 표준 프로토콜을 지원해 다양한 환경에서 활용할 수 있다.
• 인증 방식 지원
  OAuth 토큰, 쿠키 파일, HTTP 헤더 등 여러 인증 방식으로 권한이 필요한 콘텐츠에도 접근할 수 있다.
• 프록시 및 네트워크 설정
  HTTP, SOCKS 프록시를 비롯해 네트워크 타임아웃·재시도 등 다양한 네트워크 관련 설정이 가능하다.
• 설정 파일 사용
  자주 쓰는 옵션과 인증 정보를 설정 파일에 저장해 반복 입력 없이 일관된 환경을 유지할 수 있다.
• JSON 출력
  스트림 관련 데이터를 JSON 형식으로 출력하여 외부 스크립트나 도구와 쉽게 연계할 수 있다.
• 최적화된 성능 (8.0.0 이상)
  플러그인 지연 로딩(Lazy Loading) 방식을 적용하여, 프로그램 시작 시 불필요한 리소스 낭비를 줄이고 실행 속도를 높였다.

4. 지원 플랫폼

• 국내: SOOP, 치지직, 팬더티비, SBS(링크)
• 해외: 유튜브[2], 트위치, Kick, 유스트림, 크런치롤, Vimeo, 니코니코 생방송, 트윗캐스팅 등

5. 설치 방법

<rowcolor=#ffffff,#ffffff> 구분	설치 방법	설명
pip (권장)	pip install streamlink 업그레이드: pip install --upgrade streamlink	Streamlink는 Python 기반으로, OS에 관계없이 pip 로 설치할 수 있다. Python이 설치되어 있어야 하며, pip 명령이 인식되지 않는 경우 환경 변수 설정이 필요할 수 있다. 일부 OS에서는 pip3 명령을 사용해야 할 수 있다.
Windows	Windows 설치 파일 다운로드 WinGet: winget install streamlink Chocolatey: choco install streamlink	Python이 설치되어 있지 않은 Windows 사용자를 위해 .exe 설치 프로그램 또는 포터블 버전이 제공된다. 설치가 완료되면 명령 프롬프트나 PowerShell에서 streamlink 명령을 사용할 수 있다. Windows 10 이상의 64비트 환경이 필요하다.
macOS	homebrew: brew install streamlink
Linux	Streamlink AppImage 다운로드 설치 방법	Streamlink AppImage는 사용 중인 Linux 배포판이나 패키지 매니저에 관계없이 사용할 수 있는 포터블 실행 파일로, Streamlink에 Python 가상 환경이 포함된 형태이며 FFmpeg가 포함된 버전도 있다. AArch64와 x86_64 환경을 지원한다.
	Linux 배포판 패키지 매니저 Fedora: sudo dnf install streamlink Arch: sudo pacman -S streamlink	Ubuntu에서는 권장되지 않는 방법. 각 리눅스 배포판의 패키지 매니저를 통해 설치할 수 있으나, pip보다 버전이 낮을 수 있다.
소스 코드 컴파일	설치 방법	GitHub 저장소에서 소스 코드를 받아 직접 설치할 수도 있다.

• pip: {{{#!wiki style="@code@" dark-style="@codeds@"

6. 기본 명령어 및 형식

#!syntax sh
streamlink [옵션] <URL> [품질]

6.1. 스트림 품질 선택

#!syntax sh
streamlink twitch.tv/twitch

#!syntax sh
[cli][info] Found matching plugin twitch for URL twitch.tv/twitch
Available streams: audio_only, 160p (worst), 360p, 480p, 720p, 720p60, 1080p, 1080p60 (best)

#!syntax sh
streamlink twitch.tv/twitch 480p

6.2. 자주 사용되는 옵션

• 트위치 스트림을 VLC에서 최고 품질로 시청: {{{#!wiki style="@code@" dark-style="@codeds@"

• 치지직 스트림을 720p 품질로 녹화: {{{#!wiki style="@code@" dark-style="@codeds@"

6.3. 전체 CLI 명령어 목록

[ 전체 명령어 목록 펼치기 · 접기 ]

||<table width=100%><table bordercolor=#0073bd,#064d90><table bgcolor=transparent><rowbgcolor=#0073bd,#121657><rowcolor=#ffffff,#ffffff><colkeepall> 범주 ||<colkeepall> 옵션 ||<colkeepall> 설명 ||<colkeepall> 비고 ||

일반/세션	-h --help	사용 가능한 옵션과 도움말을 출력하고 종료한다.
	-V --version	설치된 Streamlink의 버전을 출력한다.
	--version-check	버전 업데이트 확인을 수행하고 종료한다.
	--auto-version-check	새 버전 자동 확인 기능을 켜거나 끈다.	기본값: no
	--locale 지역	특정 국가/언어 설정을 에뮬레이션한다.	예: \--locale en_US
	--config 경로	기본 경로 외의 다른 설정 파일을 로드한다.	여러 번 사용하여 병합 가능.
	--no-config	설정 파일을 로드하지 않는다.	순정 상태로 테스트할 때 유용.
	-l 레벨 --loglevel 레벨	로그 출력 수준을 설정한다. (debug, info, warning, error, none)	기본값: info 문제 해결 시 debug 권장.
	--logfile 경로	로그 출력을 파일로 저장한다.	- 사용 시 표준 출력으로 지정.
-Q --quiet	터미널에 로그를 출력하지 않고, 사용자 입력 요구도 비활성화한다.
플레이어	-p 경로 --player 경로	미디어 플레이어의 실행 경로를 지정한다.	가능하다면 VLC를 기본으로 사용한다.[5]
	-a 인자 --player-args 인자	플레이어에 전달할 인자를 지정한다. {playerinput} , {playertitleargs} 변수 사용 가능.	예: \player-args "\fullscreen"
	--player-env 변수	플레이어 프로세스에 환경 변수를 추가한다.	예: KEY=VALUE
	-v --player-verbose	플레이어의 콘솔 출력을 Streamlink 출력에 표시한다.
	-n --player-fifo	(Linux/macOS) 명명된 파이프(Named Pipe)를 사용해 데이터를 전달한다.
	--player-http	로컬 HTTP 서버를 열어 플레이어가 접속하게 한다.
	--player-continuous-http	HTTP 스트림 연결이 끊겨도 플레이어가 재접속하도록 유지한다.
	--player-external-http	외부 장치 접속을 허용하는 HTTP 서버를 연다.	다른 기기(스마트폰 등)에서 시청 시 사용.
	--player-external-http-port 포트	외부 HTTP 서버의 포트를 지정한다.	기본값: 0 (랜덤 포트)
	--player-passthrough 방식	Streamlink를 거치지 않고 플레이어가 직접 스트림을 처리하게 한다.	http , hls 등 지정. CPU 부하를 줄일 수 있다.
	--player-no-close	스트림 종료 후에도 플레이어 창을 닫지 않는다.	오류 메시지 확인용.
	-t 제목 --title 제목	플레이어 창의 제목(Title)을 설정한다. 지원 플레이어: mpv, PotPlayer, VLC	예: \--title "{author} - {game}"
파일 출력	-o 경로 --output 경로	스트림 데이터를 파일로 저장한다.	동시에 재생되지 않음. 예: \--output - (표준 출력)
	-r 경로 --record 경로	스트림을 재생하면서 동시에 파일로 저장한다.	예: \--record - (재생하며 표준 출력)
	-O --stdout	데이터를 표준 출력(Standard Output)으로 보낸다.	FFmpeg 등 외부 도구와 파이프 연결 시 사용.
	-f --force	출력 파일 경로에 이미 파일이 존재할 경우 덮어쓴다.
	--skip	출력 파일이 이미 존재하면 덮어쓰지 않고 건너뛴다.	--force 보다 우선순위 높음.
	--fs-safe-rules 규칙	파일 시스템 안전 규칙을 강제한다. (POSIX 또는 Windows)
	--progress 모드	다운로드 진행률 표시 방식을 변경한다.	yes , no , force
스트림 제어	--url 주소	스트림 주소를 지정한다.	명령어 맨 뒤에 주소만 적어도 된다.
	--default-stream 품질	기본으로 선택할 화질을 지정한다. 쉼표로 우선순위 지정 가능.	예: \--default-stream "1080p,best"
	--stream-url	실제 스트림 주소(M3U8 등)만 출력하고 종료한다.
	--retry-streams 시간	스트림을 찾을 때까지 지정된 시간(초)만큼 대기하며 재시도한다.	방송 시작 대기 시 유용.
	--retry-max 횟수	스트림을 찾지 못했을 때 최대 재시도 횟수.
	--retry-open 횟수	스트림을 여는 데 실패했을 때 재시도 횟수.	기본값: 1
	--stream-types	허용할 스트림 타입을 지정한다.	기본값: hls,http,*
	--stream-sorting-excludes	특정 화질을 제외하고 정렬한다.	예: --stream-sorting-excludes ">480p" (480p보다 좋은 화질만 포함)
	--check-streams	지원되는 스트림 목록만 확인하고 종료한다.
	--can-handle-url	입력된 URL을 지원하는 플러그인이 있는지 확인한다.	스크립트용 (상태 코드 반환)
웹 브라우저	--webbrowser	브라우저 API 지원을 활성화/비활성화한다.	기본값: true
	--webbrowser-executable 경로	사용할 웹 브라우저의 실행 파일 경로를 지정한다.
	--webbrowser-timeout 시간	브라우저 실행 대기 시간.
	--webbrowser-cdp-host	CDP 인터페이스 호스트.	기본값: 127.0.0.1
	--webbrowser-cdp-port	CDP 인터페이스 포트.
	--webbrowser-cdp-timeout	CDP 명령 응답 대기 시간.
	--webbrowser-headless	브라우저를 헤드리스 모드(창 없이)로 실행한다.	봇 감지 회피 시 false 권장.
네트워크	--http-proxy 주소	HTTP/HTTPS 요청에 사용할 프록시를 지정한다.	예: \--http-proxy "http://127.0.0.1:8080"
	--stream-timeout 시간	스트림 데이터 읽기 타임아웃(초).	기본값: 60.0
	--stream-segment-timeout 시간	세그먼트 다운로드 타임아웃(초).	기본값: 10.0
	--stream-segment-threads 개수	세그먼트 다운로드 병렬 스레드 수.	기본값: 1, 최대: 10
	--http-header 헤더	HTTP 요청에 사용자 정의 헤더를 추가한다.	예: \--http-header "Foo=Bar"
	--http-query-param 파라미터	HTTP 요청 URL에 쿼리 파라미터를 추가한다.	예: \--http-query-param "foo=bar"
	--http-cookie 쿠키	HTTP 요청에 쿠키를 추가한다.	인증이 필요한 스트림에 사용.
	--http-no-ssl-verify	SSL 인증서 검증을 비활성화한다.	보안상 권장되지 않음.
	--http-disable-dh	Diffie-Hellman 키 교환을 비활성화한다.
	--http-ssl-cert 파일	SSL 인증서(.pem) 파일을 지정한다.
	--http-timeout 시간	일반 HTTP 요청 타임아웃(초).	기본값: 20.0
	--interface 주소	특정 네트워크 인터페이스(IP)로 통신을 강제한다.
	-4 --ipv4	IPv4 주소만 사용한다.
	-6 --ipv6	IPv6 주소만 사용한다.
플러그인	--plugins	설치된 모든 플러그인 목록을 출력한다.
	--skip-plugins	해당 플러그인을 로드하지 않고 건너뛴다.

6.4. JSON 출력 및 메타데이터 추출

#!if 문서명2 != null
, [[jq]]

#!if 문서명3 != null
, [[]]

#!if 문서명4 != null
, [[]]

#!if 문서명5 != null
, [[]]

#!if 문서명6 != null
, [[]]

#!syntax sh
streamlink --json https://www.twitch.tv/twitch

#!syntax json
{
  "plugin": "twitch",
  "metadata": {
    "id": "123456789012",
    "author": "Twitch",
    "category": "Just Chatting",
    "title": "Twitch Stream Title"
  },
  "streams": {
    "audio_only": {
      "type": "hls",
      "url": "https://....",
      "headers": {
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:144.0)",
        "Accept-Encoding": "gzip, deflate, br, zstd",
        "Accept": "*/*",
        "Connection": "keep-alive",
        "referer": "https://player.twitch.tv",
        "origin": "https://player.twitch.tv"
      },
      "master": "https://..."
    },
    "160p": { ... },
    "360p": { ... },
    "480p": { ... },
    "720p": { ... },
    "worst": { ... },
    "best": { ... }
  }
}

#!syntax sh
streamlink -j twitch.tv/twitch | jq '.metadata'

#!syntax json
{
   "id": "123456789012",
   "author": "Twitch",
   "category": "Just Chatting",
   "title": "Twitch Stream Title"
}

#!syntax sh
streamlink -j twitch.tv/twitch | jq -r '.metadata.author'

#!syntax json
Twitch

#!syntax sh
streamlink --json https://www.twitch.tv/twitch | jq -r '.metadata.title'

#!syntax json
Twitch Stream Title

#!syntax sh
streamlink -o "{time:%Y%m%d}_{author}.ts" https://www.twitch.tv/twitch best

#!syntax sh
streamlink -o "{author}_{time:%Y%m%d_%H%M}_{category}_{title}.ts" https://www.twitch.tv/twitch best

#!syntax sh
streamlink --player mpv --title "{author} - {title}" https://www.twitch.tv/twitch best

6.5. 특정 플랫폼 전용 옵션

7. 심화 명령어

7.1. 설정 파일 사용

• 작성 예시 (config 파일):

#!syntax sh
# 기본 플레이어 설정 (경로를 자신의 환경에 맞게 수정)
player="C:\Program Files\VideoLAN\VLC\vlc.exe"

# 플레이어 옵션: 전체화면으로 시청
player-args=--fullscreen

# 기본 화질: 1080p가 있으면 1080p, 없으면 최고화질
default-stream=1080p,best

# 스트림이 종료되어도 플레이어를 닫지 않는 옵션 (선택사항)
player-no-close

# 네트워크 설정: 불안정한 인터넷 환경을 위한 타임아웃 증가
stream-timeout=60
retry-open=3

# 로그 레벨: 문제 발생 시 debug로 변경
loglevel=info

# HTTP 요청 시 특정 헤더 추가 (전역 적용)
http-header User-Agent=Mozilla/5.0

# 트위치 전용 옵션 (트위치 시청 시에만 적용됨)
twitch-low-latency
twitch-api-header Authorization=OAuth YOUR_TWITCH_TOKEN
 
# 쿠키 값 전달 (예: 네이버 로그인 토큰)
http-cookie NID_AUT=YOUR_AUT_TOKEN
http-cookie NID_SES=YOUR_SES_TOKEN

[ 기본 설정 파일(Windows x86_64) 내용 펼치기 · 접기 ]

#!syntax sh
# Streamlink config file

# Please see the Streamlink CLI documentation for all available options:
# https://streamlink.github.io/cli.html#command-line-usage

# The format is option=value
# Lines starting with a # are considered comments and are ignored.

# All leading dashes need to be ignored,
# e.g. --default-stream=STREAM becomes default-stream=STREAM

# Option values must not be quoted, or quotes become part of the option's actual value.

# ----

# By default, Streamlink will attempt to locate VLC on your system
# and use that, but you can also specify the location of a player yourself.
# Here are a couple of common player paths:

# VLC
#player=C:\Program Files\VideoLAN\VLC\vlc.exe
#player=C:\Program Files (x86)\VideoLAN\VLC\vlc.exe

# MPC-HC
#player=C:\Program Files\MPC-HC\mpc-hc64.exe
#player=C:\Program Files (x86)\MPC-HC\mpc-hc.exe

# MPV
#player=C:\Program Files\mpv-x86_64\mpv.exe

# Custom player arguments can be set using the player-args option.
# Please see the documentation of the used player for its available arguments.

# VLC
#player-args=--no-one-instance --play-and-exit
#player-args=--qt-minimal-view
#player-args=--file-caching=5000

# MPC-HC
#player-args=/new /play /close

# MPV
#player-args=--keep-open=no --force-window=yes
#player-args=--no-border
#player-args=--cache=yes --demuxer-max-bytes=2M


# Custom player window titles can automatically be set when a supported player
# and plugin are used. The title option has several variables available, which
# can show the stream's author, category/game, title, URL, etc.
#title={author} - {category} - {title}


# Use this if you want to transport the stream to the player via a named pipe.
#player-fifo

# Use one of these if you want to transport the stream to the player via HTTP.
# The continuous option will allow the player to stop and resume the output.
#player-http
#player-continuous-http

# Use player-passthrough if you want Streamlink to only pass the resolved URL
# to your player and let it handle the transport of the stream itself.
# Please note that the player needs to support the streaming protocol
# and that custom stream implementations in plugins will become unavailable,
# same as buffering options and those which change the network behavior.
#player-passthrough=http,hls

# By default, Streamlink will close the player when the stream is over.
# Use this option to let the player stay or close itself instead.
#player-no-close

# Show the player's console output
#player-verbose

# FFMPEG is used to mux separate video and audio streams into a single
# stream, so that they can be played. The full or relative path to ffmpeg
# should be specified here.
#ffmpeg-ffmpeg=C:\Program Files\Streamlink\ffmpeg\ffmpeg.exe
ffmpeg-ffmpeg=C:\Program Files\Streamlink\ffmpeg\ffmpeg.exe

# Log level, default is info
#loglevel=debug

# Number of threads to use when streaming HLS streams
#stream-segment-threads=1

7.2. 외부 플러그인 추가

7.2.1. 플러그인 디렉토리 위치

• Termux에서 pip를 통한 설치(Python 3.12)[7]:

#!syntax sh
 /data/data/com.termux/files/usr/lib/python3.12/site-packages/streamlink/plugins

7.2.2. 사용 방법

1. 신뢰할 수 있는 출처로부터 플러그인 파일(일반적으로 단일 {{{#!wiki style="@code@" dark-style="@codeds@"

1. 해당 플러그인 파일을 위에서 설명한 운영체제별 {{{#!wiki style="@code@" dark-style="@codeds@"

• 일부 복잡한 플러그인의 경우, 단일 파일이 아닌 {{{#!wiki style="@code@" dark-style="@codeds@"

1. Streamlink를 실행하면 {{{#!wiki style="@code@" dark-style="@codeds@"

#!syntax sh
streamlink --plugin-dir "/path/to/plugin" --plugin-dir "/path/to/second_plugin" <URL> [품질]

7.3. 인증 정보 활용

7.4. 고급 스트림 처리

7.5. FFmpeg 관련 옵션

7.6. Python 라이브러리로 사용

[ Python 예제 코드 펼치기 · 접기 ]

#!syntax python
import shutil
import subprocess
from typing import Any, cast

from streamlink import NoPluginError, PluginError, Streamlink
from streamlink.options import Options


def play_stream(url: str, quality: str = 'best') -> None:
    """Streamlink를 사용하여 URL의 스트림을 추출하고 VLC 플레이어로 재생한다.

    Args:
        url: 스트리밍 플랫폼의 방송 주소 (예: twitch.tv/...).
        quality: 희망하는 화질. 기본값은 'best'입니다.
    """
    # 1. 세션 생성 및 전역 옵션 설정
    session = Streamlink()
    session.set_option('http-timeout', 20)
    session.set_option('stream-timeout', 30)

    try:
        # 2. URL 해석 및 플러그인 로드
        plugin_name, plugin_class, resolved_url = session.resolve_url(url)

        # 3. 플러그인별 전용 옵션 설정
        plugin_options = Options()
        if plugin_name == 'twitch':
            plugin_options.set('low-latency', True)

        # 4. 옵션을 주입하여 플러그인 인스턴스 생성
        plugin = plugin_class(session, resolved_url, options=plugin_options)

        # 5. 사용 가능한 스트림 목록 가져오기
        streams = plugin.streams()

        # 6. 메타데이터(제목, 작성자) 추출 - VLC 창 제목 표시용
        try:
            author = plugin.get_author()
            title = plugin.get_title()
            if author and title:
                media_title = f'{author} - {title}'
            else:
                media_title = f'Streamlink - {url}'
        except (PluginError, AttributeError):
            media_title = f'Streamlink - {url}'

    except NoPluginError:
        print(f"오류: '{url}'은(는) 지원되지 않는 주소입니다.")
        return
    except PluginError as e:
        print(f'오류: 플러그인 실행 중 문제가 발생했습니다.\n{e}')
        return

    # 스트림 존재 여부 확인
    if not streams:
        print('오류: 해당 URL에서 스트림을 찾을 수 없습니다. (방송 종료 등)')
        return

    # 7. 화질 선택 로직 (Fallback)
    if quality not in streams:
        available_streams = ', '.join(streams.keys())
        print(f"알림: '{quality}' 화질이 없습니다. 사용 가능: {available_streams}")
        if 'best' in streams:
            print("대신 'best' 화질을 선택합니다.")
            quality = 'best'
        else:
            # best조차 없는 경우(오디오 전용 등) 첫 번째 스트림 선택
            quality = next(iter(streams))
            print(f"대신 '{quality}' 스트림을 선택합니다.")

    print(f'스트림 연결 중... [{quality}]')
    stream = streams[quality]

    # 8. VLC 플레이어 경로 탐색
    vlc_cmd = shutil.which('vlc')
    if not vlc_cmd:
        # Windows 기본 설치 경로 (시스템에 맞게 수정 필요)
        vlc_cmd = r'C:\Program Files\VideoLAN\VLC\vlc.exe'

    # VLC 실행 명령어 구성
    # - : 표준 입력(stdin)으로부터 데이터를 읽음
    vlc_args = [
        vlc_cmd,
        '--meta-title', media_title,
        '-'
    ]

    try:
        # 플레이어 프로세스 시작 (stdin 파이프 개방)
        player_process = subprocess.Popen(
            vlc_args,
            stdin=subprocess.PIPE
        )
    except FileNotFoundError:
        print('오류: VLC 플레이어를 찾을 수 없습니다. 설치 경로를 확인하세요.')
        return

    if player_process.stdin is None:
        print('오류: 플레이어의 표준 입력(stdin) 파이프를 열 수 없습니다.')
        player_process.terminate()
        return

    # [IDE 경고 해결] Any로 캐스팅하여 정적 분석기에게 "모든 타입을 허용함"을 명시
    process_stdin = cast(Any, player_process.stdin)

    # 9. 데이터 파이핑 (Streamlink -> VLC)
    try:
        with stream.open() as fd:
            print(f'재생 시작: {url}')
            print(f'창 제목: {media_title}')

            try:
                # shutil.copyfileobj는 대용량 데이터를 효율적으로 버퍼링하여 복사한다.
                shutil.copyfileobj(fd, process_stdin)
            except BrokenPipeError:
                print('플레이어가 종료되었습니다.')
            except OSError as e:
                # Windows 파이프 종료 이슈(Errno 22) 처리
                if e.errno == 22:
                    print('플레이어가 종료되었습니다. (정상)')
                else:
                    print(f'네트워크 또는 재생 오류 발생: {e}')

    except Exception as e:
        print(f'스트림을 여는 중 오류 발생: {e}')
    finally:
        # 10. 리소스 정리 및 프로세스 종료
        try:
            if player_process.stdin:
                player_process.stdin.close()
        except OSError:
            pass

        if player_process.poll() is None:
            player_process.terminate()
            player_process.wait()
        print('종료되었습니다.')


if __name__ == '__main__':
    _TARGET_URL = 'https://www.twitch.tv/twitch'
    play_stream(_TARGET_URL, quality='1080p60')

• GUI 기반 치지직 녹화 프로그램
• 특정 플랫폼의 API를 직접 사용하지 않고 Streamlink를 통한 온라인 상태 확인, 또는 이와 연계한 알림 발송이나 자동 녹화 기능 개발
• Streamlink Twitch GUI와 같이 특정 플랫폼에 특화된 편의 기능을 제공하는 서드파티 프로그램
• 다운로드한 스트림 데이터를 분석하거나, 다른 미디어 처리 파이프라인의 일부로 통합하는 등 보다 복잡한 자동화 시스템 구축

7.6.1. 세션 및 옵션 관리

1. Streamlink 세션 객체를 통해 전역 설정을 관리하고 플러그인을 로드한다.
2. {{{#!wiki style="@code@" dark-style="@codeds@"

#!syntax python
from streamlink import Streamlink
from streamlink.options import Options

# 1. 세션 생성
session = Streamlink()

# 2. 전역 옵션 설정 (모든 연결에 적용)
# 예: HTTP 타임아웃 20초 설정
session.set_option("http-timeout", 20)

# 프록시 설정 (http-proxy 옵션 하나로 HTTP/HTTPS 모두 적용됨)
session.set_option("http-proxy", "http://127.0.0.1:8080")

# 3. 특정 플러그인 전용 옵션 설정 (Options 객체 활용)
# 예: 트위치 저지연 모드 활성화
twitch_options = Options()
twitch_options.set("low-latency", True)

# 4. 플러그인 로드 및 옵션 적용
# URL에 맞는 플러그인 클래스를 찾고, 위에서 만든 옵션을 주입한다.
plugin_name, plugin_class, resolved_url = session.resolve_url("https://www.twitch.tv/twitch")
plugin = plugin_class(session, resolved_url, options=twitch_options)

7.6.2. 데이터 유효성 검사 및 메타데이터 추출

[ Python 예제 코드 펼치기 · 접기 ]

#!syntax python
from typing import Any, Dict

from streamlink import NoPluginError, PluginError, Streamlink
from streamlink.plugin.api import validate


def get_stream_metadata(url: str) -> str:
    """URL에서 스트림 메타데이터(작성자, 제목)를 안전하게 추출하여 반환한다.

    Streamlink의 validate 모듈을 사용하여 API 응답 구조를 검증한다.

    Args:
        url: 대상 스트림 URL.

    Returns:
        포맷팅된 메타데이터 문자열 또는 오류 발생 시 에러 메시지.
    """
    session = Streamlink()
    session.set_option('http-timeout', 10)

    try:
        # 플러그인 로드
        _, _, resolved_url = session.resolve_url(url)
        plugin = session.resolve_url(url)[1](session, resolved_url)

        # 1. 원본 메타데이터 추출 (API 호출)
        raw_metadata: Dict[str, Any] = {
            'id': plugin.get_id(),
            'author': plugin.get_author(),
            'title': plugin.get_title()
        }

        # 2. 데이터 유효성 검사 스키마 정의 (Schema)
        # validate.any(type, None)은 값이 해당 타입이거나 None인 경우를 모두 허용한다.
        schema = validate.Schema({
            'id': validate.any(int, str, None),
            'author': validate.any(str, None),
            'title': validate.any(str, None)
        })

        # 3. 검증 실행 (스키마와 맞지 않으면 PluginError 발생)
        data = schema.validate(raw_metadata)

        # 4. 결과 포맷팅 및 반환
        author = data.get('author')
        title = data.get('title')

        if author and title:
            return f'[{author}] {title}'
        if author:
            return f'[{author}] 방송 제목 없음'

        return f'메타데이터 없음 ({url})'

    except NoPluginError:
        return '오류: 지원되지 않는 URL입니다.'
    except PluginError as e:
        return f'오류: 플러그인 실행 중 문제 발생 ({e})'
    except Exception as e:
        return f'알 수 없는 오류: {e}'


if __name__ == '__main__':
    _TARGET_URL = 'https://www.twitch.tv/twitch'
    print(get_stream_metadata(_TARGET_URL))

7.6.3. 예외 처리

• {{{#!wiki style="@code@" dark-style="@codeds@"

• {{{#!wiki style="@code@" dark-style="@codeds@"

• {{{#!wiki style="@code@" dark-style="@codeds@"

#!syntax python
from streamlink import Streamlink, NoPluginError, PluginError

session = Streamlink()
try:
    streams = session.streams("https://unsupported-site.com")
except NoPluginError:
    print("지원하지 않는 URL입니다.")
except PluginError as e:
    print(f"플러그인 처리 중 오류 발생: {e}")

7.7. Termux 및 VLC와 연계

1. 먼저, Termux를 실행하고 콘솔에 다음과 같이 입력하여 리포지토리를 업데이트한다.
   {{{#!syntax sh

1. 필요한 패키지를 설치한다.
   {{{#!syntax sh

1. (선택 사항) CFLAGS 환경 변수를 설정한다. (빌드 오류 발생 시)
   {{{#!syntax sh

1. (선택 사항) lxml 라이브러리를 재설치한다. (빌드 오류 발생 시)
   {{{#!syntax sh

1. streamlink 라이브러리를 설치한다.
   {{{#!syntax sh

1. 다음과 같이 셸 스크립트를 생성한다. (예: {{{#!wiki style="@code@" dark-style="@codeds@"

1. slink 스크립트 파일에 심볼릭 링크를 생성하고 실행 권한을 부여한다. (이때, 기본 홈 디렉토리에 slink 파일이 있다고 가정)
   {{{#!syntax sh

1. slink 파일을 다음과 같이 실행한다. (원격 SSH 셸에서 실행할 경우, Termux가 반드시 포그라운드에 실행되고 있어야 한다.)
   {{{#!syntax sh

8. 활용 사례

• 저사양 시스템에서의 스트리밍 활용
  웹 브라우저는 많은 시스템 자원을 소모하는 경향이 있다. Streamlink는 CLI 기반으로 작동하므로, 웹 브라우저 UI 없이 스트림 데이터만 직접 처리하여 Raspberry Pi와 같은 임베디드 환경, 저사양 HTPC나 구형 컴퓨터에서도 비교적 쾌적하게 스트리밍 콘텐츠를 즐기거나 녹화하는 데 활용될 수 있다.
• 다중 스트림 동시 처리
  Streamlink는 여러 인스턴스를 동시에 실행할 수 있으므로, 여러 개의 스트림을 동시에 시청하거나 녹화하는 것이 가능하다. 예를 들어, 여러 플랫폼에서 진행되는 e스포츠 경기를 한 번에 녹화하거나, 각기 다른 방송을 여러 플레이어 창에 띄워놓고 모니터링하는 용도로 사용할 수 있다. 각 Streamlink 프로세스는 독립적으로 작동하며, 설정 파일이나 명령줄 옵션을 통해 각기 다른 플레이어나 저장 경로를 지정할 수 있다.

8.1. 유로 트럭 시뮬레이터 2에서 사용

#!if (문단 == null) == (앵커 == null)
를

#!if 문단 != null & 앵커 == null
의 [[유로 트럭 시뮬레이터 2#s-|]]번 문단을

#!if 문단 == null & 앵커 != null
의 [[유로 트럭 시뮬레이터 2#인터넷 방송을 이용하는 방법|인터넷 방송을 이용하는 방법]] 부분을

8.2. 개인 스트리밍 중계 서버 구축

• 구성 예시
1. Streamlink: 방송 원본 소스 추출 (파이프 출력)
2. FFmpeg: 스트림을 받아 HLS 세그먼트(.ts)와 재생 목록(.m3u8)으로 실시간 변환 및 저장
3. Web Server: 변환된 파일이 저장된 폴더를 HTTP로 호스팅

• 명령어 예시 (Linux/macOS)

#!syntax sh
streamlink --stdout twitch.tv/twitch best | \
ffmpeg -i - \
  -c:v copy -c:a copy \
  -f hls -hls_time 4 -hls_list_size 5 \
  -hls_flags delete_segments \
  /var/www/html/stream/playlist.m3u8

8.3. 자동 녹화 환경 구축

#!syntax sh
0 21 * * * streamlink -o "/home/namu/녹화폴더/$(date +\%Y\%m\%d)_방송제목.ts" twitch.tv/채널명 best >> /var/log/stream_record.log 2>&1

• Windows: {{{#!wiki style="@code@" dark-style="@codeds@"

• Linux: {{{#!wiki style="@code@" dark-style="@codeds@"

[ 자동 녹화 Python 스크립트 펼치기 · 접기 ]

#!syntax python
from datetime import datetime
from http.client import HTTPException
import shutil
import subprocess
import time
from typing import Any, Optional, cast

import requests
from streamlink import Streamlink, StreamError

# 브라우저처럼 보이게 하는 HTTP 헤더 상수 (모듈 레벨 상수)
_HEADERS = {
    'User-Agent': (
        'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:145.0) '
        'Gecko/20100101 Firefox/145.0'
    ),
    'Accept': 'application/json, text/plain, */*'
}


def validate_channel(request_id: str) -> Optional[str]:
    """채널 ID가 유효한지 확인하고 채널명을 반환한다.

    Args:
        request_id: 치지직 채널 고유 ID.

    Returns:
        유효한 경우 채널명을 반환하고, 그렇지 않으면 None을 반환한다.
    """
    api_url = f'https://api.chzzk.naver.com/service/v1/channels/{request_id}'

    try:
        response = requests.get(api_url, headers=_HEADERS, timeout=10)
        response.raise_for_status()
        content = response.json().get('content', {})

        if not content.get('channelId'):
            return None
        return content.get('channelName')
    except (requests.RequestException, HTTPException) as e:
        print(f'채널 확인 중 에러 발생: {e}')
        return None


def wait_online_state(request_id: str) -> str:
    """방송이 시작될 때까지 10초 간격으로 상태를 확인(Polling)한다.

    Args:
        request_id: 치지직 채널 고유 ID.

    Returns:
        방송이 시작되면 방송 제목을 반환한다.
    """
    channel_url = f'https://api.chzzk.naver.com/service/v1/channels/{request_id}'
    live_url = (
        f'https://api.chzzk.naver.com/polling/v2/channels/{request_id}/live-status'
    )

    while True:
        try:
            # 1. 채널 상태 확인 (Live 여부 flag)
            response = requests.get(channel_url, headers=_HEADERS, timeout=10)
            response.raise_for_status()
            channel_content = response.json().get('content', {})

            if channel_content.get('openLive'):
                # 2. 방송 상세 정보 확인 (제목 등)
                response = requests.get(live_url, headers=_HEADERS, timeout=10)
                response.raise_for_status()
                live_content = response.json().get('content', {})

                title = live_content.get('liveTitle', '제목 없음')
                print(f'방송 시작 감지! (제목: {title})')
                return title

            print('방송 오프라인... 10초 후 재확인')
            time.sleep(10)
        except Exception as e:
            print(f'상태 확인 중 오류 발생: {e}')
            time.sleep(10)


def streamlink_record(
    request_id: str,
    quality: str = 'best',
    stream_author: str = '',
    stream_title: str = ''
) -> None:
    """Streamlink로 스트림을 추출하고 FFmpeg를 통해 실시간 MP4 파일로 저장한다.

    Args:
        request_id: 채널 ID.
        quality: 희망 화질. 기본값은 'best'입니다.
        stream_author: 메타데이터용 스트리머 이름.
        stream_title: 메타데이터용 방송 제목.
    """
    # FFmpeg 설치 여부 확인
    if not shutil.which('ffmpeg'):
        print('오류: FFmpeg가 설치되어 있지 않거나 PATH 환경변수에 없습니다.')
        return

    url = f'https://chzzk.naver.com/live/{request_id}'

    # 세션 생성 및 HTTP 헤더 설정
    session = Streamlink()
    session.set_option('http-headers', _HEADERS)
    session.set_option('http-timeout', 30)

    try:
        print('스트림 정보를 가져오는 중...')
        streams = session.streams(url)
    except StreamError as e:
        print(f'스트림 열기 실패: {e}')
        return

    if not streams:
        print('활성화된 스트림을 찾을 수 없습니다.')
        return

    # 화질 선택 로직 (Fallback 지원)
    if quality not in streams:
        available = ', '.join(streams.keys())
        print(f"알림: '{quality}' 화질이 없습니다. 사용 가능: {available}")
        if 'best' in streams:
            print("대신 'best' 화질로 녹화를 시도합니다.")
            quality = 'best'
        else:
            quality = next(iter(streams))
            print(f"대신 '{quality}' 화질을 선택합니다.")

    stream = streams[quality]
    timestamp = datetime.now().strftime('%Y-%m-%d_%H-%M-%S')
    filename = f'{stream_author}_{timestamp}_{quality}.mp4'

    print(f'녹화 시작 (FFmpeg 연동): {filename}')

    # FFmpeg 명령어 구성
    # -c copy: 재인코딩 없이 복사 (CPU 부하 최소화)
    # -metadata: 파일 속성에 제목 및 아티스트 정보 삽입
    ffmpeg_cmd = [
        'ffmpeg',
        '-y',                 # 파일 덮어쓰기
        '-loglevel', 'error', # 로그 최소화
        '-i', '-',            # stdin 입력
        '-c', 'copy',         # 스트림 복사
        '-metadata', f'title={stream_title}',
        '-metadata', f'artist={stream_author}',
        '-f', 'mp4',          # MP4 포맷 강제
        filename
    ]

    ffmpeg_process = None

    try:
        # FFmpeg 프로세스 시작 (stdin 파이프 개방)
        ffmpeg_process = subprocess.Popen(ffmpeg_cmd, stdin=subprocess.PIPE)

        if ffmpeg_process.stdin is None:
            print('FFmpeg 파이프를 열 수 없습니다.')
            return

        # IDE 타입 경고 방지
        process_stdin = cast(Any, ffmpeg_process.stdin)

        # Streamlink 데이터를 FFmpeg로 파이핑 (실시간 저장)
        with stream.open() as fd:
            shutil.copyfileobj(fd, process_stdin)

    except KeyboardInterrupt:
        print('\n사용자에 의해 녹화가 중단되었습니다. 저장 중인 파일을 마무리합니다...')
    except OSError as e:
        # 파이프가 깨진 경우(Broken pipe)는 정상 종료로 간주할 수 있음
        if e.errno == 22 or e.errno == 32:
            pass
        else:
            print(f'파일 쓰기 또는 네트워크 오류 발생: {e}')
    finally:
        # 프로세스 및 파일 안전 종료 처리 (Moov atom 기록 보장)
        if ffmpeg_process:
            if ffmpeg_process.stdin:
                try:
                    ffmpeg_process.stdin.close()
                except OSError:
                    pass
            ffmpeg_process.wait()

        print('녹화가 종료되었습니다.')


if __name__ == '__main__':
    # 치지직 채널 고유 ID 입력 (URL의 마지막 부분)
    _CHANNEL_ID = '치지직_채널_ID'

    # 1. 채널 유효성 검사
    _author = validate_channel(_CHANNEL_ID)
    if not _author:
        print('유효하지 않은 채널입니다.')
        exit(1)

    # 2. 방송 시작 대기 (Polling)
    _title = wait_online_state(_CHANNEL_ID)

    # 3. 녹화 시작
    streamlink_record(
        _CHANNEL_ID,
        quality='1080p',
        stream_author=_author,
        stream_title=_title
    )

9. 여담

• Streamlink는 DRM으로 보호된 콘텐츠는 기술적, 법적 문제로 인해 처리할 수 없다.
• 스트리밍 플랫폼의 웹사이트 구조나 API가 변경되면 해당 플랫폼의 플러그인이 갑자기 작동하지 않을 수 있다. 이 경우 Streamlink를 업데이트하거나 개별 플러그인을 불러오면 문제가 해결될 수 있다. Streamlink의 GitHub Issues에서 플러그인 업데이트 관련 요청을 처리하고 있으며 업데이트에 반영되기까지 다소간의 시일이 소요된다. 치지직의 경우 베타 서비스가 종료되기까지 공식적으로 지원하지 않았으며, 아프리카TV가 SOOP로 이름이 바뀐 이후에도 수일이 지나 업데이트에 반영됐다.
• Streamlink 사용과 관련한 오류가 발생할 경우에는 최신 버전으로 업데이트하거나, {{{#!wiki style="@code@" dark-style="@codeds@"

• 일부 비주류 플랫폼의 플러그인은 다른 주요 플러그인만큼 안정적이지 않거나 유지보수가 더딜 수 있다.
• 사용자의 네트워크 환경(방화벽, VPN 등)에 따라 스트림 연결에 문제가 발생할 수 있다.

10. 관련 문서

• 오픈 소스
• VLC
• youtube-dl → yt-dlp: Streamlink에서는 유튜브 동영상 다운로드를 지원하지 않지만 이쪽은 가능하다.

11. 외부 링크

• Streamlink 공식 웹사이트
• Streamlink GitHub 저장소
• PyPI 프로젝트 페이지
• Streamlink Windows 빌드 릴리즈 페이지
• Streamlink AppImages 빌드 릴리즈 페이지
• Streamlink Twitch GUI GitHub 저장소
• CLI 명령어 가이드 (공식 문서)
• 플러그인 가이드 (공식 문서)
• mpv: MPlayer의 후신인 프로젝트이다.