docs/kr/README.md
<a href="https://trendshift.io/repositories/13360" target="_blank"></a>
English｜简体中文｜日本語｜한국어｜Tiếng Việt｜Français｜Deutsch｜Español｜Português｜Русский｜اللغة العربية
</div>KrillinAI는 Krillin AI 팀이 개발한 다목적 오디오 및 비디오 현지화 및 향상 솔루션으로, 인간 사용자와 AI 에이전트 모두를 위해 설계되었습니다. 비디오 다운로드, 음성 전사, 자막 번역, TTS 더빙, 세로 변환, 커버 생성 등 완전한 파이프라인을 포괄하며 가로 및 세로 형식을 지원하여 모든 주요 플랫폼(Bilibili, Xiaohongshu, Douyin, WeChat Video, Kuaishou, YouTube, TikTok 등)에서 완벽한 프레젠테이션을 보장합니다. 인간 사용자는 클라이언트를 통해 원클릭으로 엔드투엔드 콘텐츠 현지화를 완료할 수 있으며, 각 기능은 CLI를 통해 독립적으로 호출할 수도 있어 AI 에이전트가 단일 또는 여러 단계를 필요에 따라 편성하여 유연한 자동화 워크플로를 구성할 수 있습니다.
🤖 CLI 지원: 각 단계가 독립적으로 실행되고 구조화된 결과를 출력하는 단계별 명령줄 인터페이스를 제공하며, 단계 간 아티팩트 재사용을 지원합니다.
🧩 Skills 컬렉션: skills/ 디렉토리에 AI 에이전트가 안정적인 계약에 따라 직접 호출할 수 있는 각 단계별 Skills가 제공되어 CLI 문서를 직접 파싱할 필요가 없습니다.
🔗 Pipeline 편성: 여러 단계를 한 명령으로 연결하여 다운로드부터 렌더링까지 전체 프로세스를 자동화합니다.
🖼️ 커버 생성: 원본 비디오 썸네일과 프롬프트 템플릿에서 플랫폼 커버 이미지를 자동으로 생성합니다.
📥 비디오 수집: yt-dlp 다운로드 또는 로컬 파일 업로드 지원
📜 정확한 인식: Whisper 기반의 고정밀 음성 인식
🧠 지능형 분할: LLM을 사용한 자막 분할 및 정렬
🔄 용어 교체: 전문 용어의 원클릭 교체
🌍 전문 번역: 자연스러운 의미를 유지하기 위한 LLM 번역
🎙️ 음성 클로닝: CosyVoice의 선택된 음성 톤 또는 사용자 정의 음성 클로닝 제공
🎬 비디오 구성: 가로 및 세로 비디오 및 자막 레이아웃 자동 처리
💻 크로스 플랫폼: Windows, Linux, macOS 지원, 데스크탑·서버·CLI 세 가지 사용 방식 제공
아래 이미지는 46분 길이의 로컬 비디오를 가져와 원클릭으로 실행한 후 생성된 자막 파일의 효과를 보여줍니다. 수동 조정 없이도 누락이나 겹침이 없고, 분할이 자연스럽고, 번역 품질이 매우 높습니다.
<table> <tr> <td width="33%">https://github.com/user-attachments/assets/bba1ac0a-fe6b-4947-b58d-ba99306d0339
</td> <td width="33%">https://github.com/user-attachments/assets/0b32fad3-c3ad-4b6a-abf0-0865f0dd2385
</td> <td width="33%">https://github.com/user-attachments/assets/c2c7b528-0ef8-4ba9-b8ac-f9f92f6d4e71
</td> </tr> </table>아래 표의 모든 로컬 모델은 실행 파일 + 모델 파일의 자동 설치를 지원합니다. 선택하기만 하면 Klic이 모든 것을 준비합니다.
| 서비스 출처 | 지원 플랫폼 | 모델 옵션 | 로컬/클라우드 | 비고 |
|---|---|---|---|---|
| OpenAI Whisper | 모든 플랫폼 | - | 클라우드 | 빠른 속도와 좋은 효과 |
| FasterWhisper | Windows/Linux | tiny/medium/large-v2 (추천: medium+) | 로컬 | 빠른 속도, 클라우드 서비스 비용 없음 |
| WhisperKit | macOS (M 시리즈 전용) | large-v2 | 로컬 | Apple 칩에 대한 네이티브 최적화 |
| WhisperCpp | 모든 플랫폼 | large-v2 | 로컬 | 모든 플랫폼 지원 |
| Alibaba Cloud ASR | 모든 플랫폼 | - | 클라우드 | 중국 본토의 네트워크 문제 회피 |
✅ OpenAI API 사양을 준수하는 모든 클라우드/로컬 대형 언어 모델 서비스와 호환됩니다. 여기에는 다음이 포함되지만 이에 국한되지 않습니다:
지원되는 입력 언어: 중국어, 영어, 일본어, 독일어, 터키어, 한국어, 러시아어, 말레이어(지속적으로 증가 중)
지원되는 번역 언어: 영어, 중국어, 러시아어, 스페인어, 프랑스어 및 기타 101개 언어
KrillinAI의 Deepwiki에서 질문할 수 있습니다. 이곳은 리포지토리의 파일을 색인화하여 빠르게 답변을 찾을 수 있습니다.
먼저, Release에서 장치 시스템에 맞는 실행 파일을 다운로드한 후, 아래 튜토리얼에 따라 데스크탑 버전 또는 비데스크탑 버전을 선택합니다. 소프트웨어 다운로드를 빈 폴더에 두세요. 실행하면 일부 디렉토리가 생성되며, 빈 폴더에 두면 관리가 더 쉬워집니다.
【데스크탑 버전인 경우, 즉 "desktop"이 포함된 릴리스 파일인 경우, 여기를 참조하세요】 데스크탑 버전은 새로운 사용자가 구성 파일을 올바르게 편집하는 데 어려움을 겪는 문제를 해결하기 위해 새로 출시되었으며, 지속적으로 업데이트되는 몇 가지 버그가 있습니다.
【비데스크탑 버전인 경우, 즉 "desktop"이 포함되지 않은 릴리스 파일인 경우, 여기를 참조하세요】 비데스크탑 버전은 초기 버전으로, 구성은 더 복잡하지만 기능적으로 안정적이며 서버 배포에 적합합니다. 웹 형식의 UI를 제공합니다.
config 폴더를 생성한 후, config 폴더 내에 config.toml 파일을 생성합니다. 소스 코드의 config 디렉토리에서 config-example.toml 파일의 내용을 config.toml에 복사하고 주석에 따라 구성 정보를 입력합니다.http://127.0.0.1:8888에 접속하여 사용을 시작합니다 (8888을 구성 파일에서 지정한 포트로 교체).【데스크탑 버전인 경우, 즉 "desktop"이 포함된 릴리스 파일인 경우, 여기를 참조하세요】 서명 문제로 인해 현재 데스크탑 버전은 두 번 클릭하여 실행하거나 dmg를 통해 설치할 수 없습니다. 애플리케이션을 수동으로 신뢰해야 합니다. 방법은 다음과 같습니다:
sudo xattr -cr ./KrillinAI_1.0.0_desktop_macOS_arm64
sudo chmod +x ./KrillinAI_1.0.0_desktop_macOS_arm64
./KrillinAI_1.0.0_desktop_macOS_arm64
【비데스크탑 버전인 경우, 즉 "desktop"이 포함되지 않은 릴리스 파일인 경우, 여기를 참조하세요】 이 소프트웨어는 서명되지 않았으므로 macOS에서 실행할 때 "기본 단계"에서 파일 구성을 완료한 후에도 애플리케이션을 수동으로 신뢰해야 합니다. 방법은 다음과 같습니다:
실행 파일이 있는 디렉토리에서 터미널을 엽니다 (파일 이름이 KrillinAI_1.0.0_macOS_arm64라고 가정).
다음 명령을 순서대로 실행합니다:
sudo xattr -rd com.apple.quarantine ./KrillinAI_1.0.0_macOS_arm64
sudo chmod +x ./KrillinAI_1.0.0_macOS_arm64
./KrillinAI_1.0.0_macOS_arm64
이렇게 하면 서비스가 시작됩니다.
이 프로젝트는 Docker 배포를 지원합니다. Docker 배포 지침을 참조하세요.
KrillinAI는 스크립트, 자동화 파이프라인, AI Agent가 호출하기 쉬운 단계형 CLI를 제공합니다. CLI는 기본적으로 동기 실행되며, 완료 후 stdout에 JSON 한 줄을 출력하고 작업 디렉터리에 krillinai_manifest.json을 기록하여 이후 단계가 기존 산출물을 재사용할 수 있게 합니다.
소스에서 CLI 빌드:
go build -o build/krillinai-cli ./cmd/cli
명령 개요:
| 명령 | 용도 | 주요 산출물 |
|---|---|---|
subtitle | YouTube / Bilibili 링크 또는 로컬 영상에서 자막을 생성합니다. 플랫폼 자막을 우선 다운로드하고 실패하면 Whisper 전사로 대체합니다 | origin_language_srt.srt, target_language_srt.srt, bilingual_srt.srt, short_origin_mixed_srt.srt |
tts | 목표 언어 자막을 기반으로 목표 언어 더빙을 생성합니다 | tts_final_audio.wav, video_with_tts.mp4 |
render-horizontal | 가로 영상을 생성합니다: 원본 영상 + 이중 언어 자막, 또는 더빙 영상 + 목표 언어 자막 | horizontal_bilingual.mp4 |
render-vertical | 세로 영상을 생성합니다: 원본 영상을 세로로 변환 + 짧은 자막, 또는 더빙 영상 + 목표 언어 자막 | transferred_vertical_video.mp4, vertical_bilingual.mp4 |
pipeline | outputs에 따라 여러 단계를 연결합니다 | 선택한 단계에 따라 다름 |
cover | 원본 영상 커버와 prompt 템플릿으로 커버를 생성합니다 | generated_cover.png |
일반적인 워크플로:
# 1. 원본 언어, 목표 언어, 이중 언어 자막, 세로 영상용 짧은 자막 생성
./build/krillinai-cli subtitle "https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
--origin-lang en \
--target-lang zh_cn \
--workdir tasks/demo \
--caption-source any
# 2. 목표 언어 자막으로 더빙 생성
./build/krillinai-cli tts \
--workdir tasks/demo \
--input-srt tasks/demo/target_language_srt.srt \
--line-mode target-only \
--video tasks/demo/origin_video.mp4
# 3. 이중 언어 자막이 포함된 가로 영상 생성
./build/krillinai-cli render-horizontal \
--workdir tasks/demo \
--video tasks/demo/origin_video.mp4 \
--subtitle tasks/demo/bilingual_srt.srt
# 4. 짧은 이중 언어 자막이 포함된 세로 영상 생성
./build/krillinai-cli render-vertical \
--workdir tasks/demo \
--video tasks/demo/origin_video.mp4 \
--subtitle tasks/demo/short_origin_mixed_srt.srt \
--major-title "오늘의 주제" \
--minor-title "AI Video"
Agent 통합 규칙:
krillinai_manifest.json을 우선 읽으세요. 일반 로그를 파싱하지 마세요.outputs 필드는 산출물 경로를 기록하며, 이후 명령은 --workdir만 전달해 manifest를 재사용할 수 있습니다.--dry-run은 영상을 다운로드하거나 외부 AI 서비스를 호출하지 않고 매개변수를 검증하고 manifest를 생성합니다.error.kind에 따라 오류를 처리하세요: usage는 매개변수 수정, retryable은 재시도, dependency는 ffmpeg / ffprobe / yt-dlp 설치가 필요합니다.더 자세한 매개변수 설명은 CLI 기능 요약을 참고하세요.
이 저장소는 Agent가 안정적인 규칙으로 CLI를 호출할 수 있도록 skills/ 아래에 바로 사용할 수 있는 Agent Skills도 제공합니다:
krillinai-cli: 자막, TTS, 렌더링, pipeline 또는 커버 워크플로를 선택하는 최상위 진입 skill입니다.krillinai-subtitle, krillinai-tts, krillinai-render-horizontal, krillinai-render-vertical: 단계별 운영 가이드입니다.krillinai-pipeline 및 krillinai-cover: pipeline 오케스트레이션과 커버 생성을 위한 계획/예약 가이드이며, 해당 실행 경로가 완전히 연결될 때까지 계획 용도로 사용합니다.cli-contract.md: JSON, manifest, outputs, 오류 처리에 대한 공통 계약입니다.제공된 구성 파일을 기반으로, README 파일의 "구성 도움말(반드시 읽어야 함)" 섹션을 업데이트한 내용은 다음과 같습니다:
구성 파일은 여러 섹션으로 나뉩니다: [app], [server], [llm], [transcribe], [tts]. 작업은 음성 인식(transcribe) + 대형 모델 번역(llm) + 선택적 음성 서비스(tts)로 구성됩니다. 이를 이해하면 구성 파일을 더 잘 파악할 수 있습니다.
가장 쉽고 빠른 구성:
자막 번역만을 위한 경우:
[transcribe] 섹션에서 provider.name을 openai로 설정합니다.[llm] 블록에 OpenAI API 키만 입력하면 자막 번역을 시작할 수 있습니다. app.proxy, model, openai.base_url은 필요에 따라 입력할 수 있습니다.비용, 속도 및 품질의 균형 (로컬 음성 인식 사용):
[transcribe] 섹션에서 provider.name을 fasterwhisper로 설정합니다.transcribe.fasterwhisper.model을 large-v2로 설정합니다.[llm] 블록에 대형 언어 모델 구성을 입력합니다.텍스트 음성 변환(TTS) 구성 (선택 사항):
[tts] 섹션에서 provider.name을 설정합니다 (예: aliyun 또는 openai).aliyun을 선택하면 [tts.aliyun] 섹션을 입력해야 합니다.aliyun을 선택해야 합니다.Alibaba Cloud 구성:
AccessKey, Bucket, AppKey를 얻는 방법에 대한 자세한 내용은 Alibaba Cloud 구성 지침을 참조하세요. AccessKey 등의 반복 필드는 명확한 구성 구조를 유지하기 위해 설계되었습니다.자주 묻는 질문을 방문하세요.