# 셀비 제품 소개와 설치·첫 프로젝트

> 기준일: 2026-09-19
> 대상: 처음 사용하는 회원, AI 상담 답변 작성자, selvi.web 안내 콘텐츠 담당자
> 검증 범위: 현재 저장소의 화면 문구와 실행 경로를 대조했다. 이 문서 작성 과정에서 설치·로그인·유료 API의 실제 성공을 시험한 것은 아니다.

## KB-START-001 · 셀비는 어떤 프로그램인가요?

셀비는 상품을 소개하는 짧은 영상을 만드는 데스크톱 제작 프로그램이다. 참고할 아이템을 찾고, 사용할 원본 영상을 준비한 뒤, 대본·음성·장면·자막·디자인을 편집하여 완성본을 만든다. 만들어진 영상과 게시 정보를 UUP에 전달하는 단계까지 제공한다.

핵심 구분은 다음과 같다.

- **셀비 데스크톱 앱**: 로컬 프로젝트·영상 파일을 관리하고 제작·렌더링한다. AI 대본, AI 음성 등은 선택한 외부 공급자에 요청한다.
- **selvi.kr 웹사이트**: 회원 계정·사용 기간과 다운로드·사용 안내·업데이트 내역 등을 제공한다. 웹사이트만 열어서 데스크톱의 로컬 제작 작업이 실행되는 것은 아니다.
- **UUP**: 셀비가 전달한 자료를 받아 계정별 게시·예약 등 후속 작업을 담당한다. 셀비에서 UUP 전달 성공을 확인한 것과 SNS에 실제 게시된 것은 서로 다른 상태다.

영상 제작 외에 **캐러셀** 메뉴도 있다. 이 문서의 6단계는 영상 프로젝트에 대한 흐름이며 캐러셀 제작과는 구분한다. 셀비의 분석·추천·대본은 제작 보조 기능이다. 특정 상품의 매출이나 영상 조회수, 다운로드 가능한 모든 사이트를 보장하는 기능으로 설명하지 않는다.

## KB-START-002 · 설치와 실행 준비

공식 다운로드는 [selvi.kr](https://selvi.kr)에서 시작한다. 공개 릴리스의 배포 파일은 Windows 64비트용 `selvi-windows-amd64.zip`과 macOS Apple Silicon용 `selvi-darwin-arm64.app.zip`이다. [공식 다운로드 게시판](https://selvi.kr/download)에서 로그인·사용 기간 조건과 최신 버전을 확인할 수 있다. 다른 CPU나 운영체제 지원을 이 목록만으로 확대 해석하지 않는다.

1. 사용하는 운영체제에 맞는 파일을 내려받는다.
2. 압축을 풀고 실행 파일 또는 앱을 실행한다. 압축 내부에서 바로 실행하지 않는다.
3. 로그인 후 **설정 → 환경 검사**에서 **다시 검사**를 누른다.
4. FFmpeg·ffprobe, 미리보기 서버, WebView2, 저장 폴더의 상태를 확인한다.
5. 문제가 있는 항목에 표시된 안내를 수행하고 다시 검사한다.

FFmpeg·ffprobe는 영상 분석·변환·렌더에 사용하는 도구다. 자동 설치를 지원하는 환경에서는 없거나 오래된 도구를 내려받아 검증·설치한다. 화면에 **이 플랫폼은 FFmpeg를 직접 설치해야 합니다**가 표시되는 환경에서는 별도로 준비해야 한다. **FFmpeg 다시 받기**는 지원 환경에서 조치가 필요할 때 표시된다.

실행창이 떴다는 것만으로 제작 도구가 모두 준비된 것은 아니다. 앱 안의 **제작 환경** 상태와 **환경 검사** 결과를 기준으로 다음 단계를 안내한다.

## KB-START-003 · 로그인과 사용 기간

1. 로그인 화면에서 **Google로 계속**을 누른다.
2. 열린 브라우저에서 selvi.kr에서 사용하는 Google 계정으로 로그인한다.
3. 앱으로 돌아와 계정 및 사용 기간 확인을 마친다.
4. 사용 기간 안내가 표시되면 **selvi.kr 마이페이지 열기**에서 계정을 확인하고, 상태가 갱신된 뒤 **다시 확인**한다.

앱은 Google 계정과 서버의 사용 권한을 확인한다. 웹사이트의 계정과 앱의 계정이 다르면 기대한 사용 기간이 보이지 않을 수 있다. 사용 권한이 끝났거나 회수된 상태를 앱이 확인하면 세션을 지우고 로그인 화면으로 돌아간다. 네트워크 상태에 관계없이 서버 변경을 같은 순간에 감지한다고 설명하지 않는다.

AI 상담은 계정의 실제 잔여 기간을 이 문서만으로 알 수 없다. 사용자가 보고 있는 안내를 기준으로 설명하고, 기간 부여·연장 완료를 임의로 선언하지 않는다.

## KB-START-004 · 처음 필요한 설정

**설정 → 화면과 저장**에서 저장 폴더를 확인한다. 프로젝트는 선택한 저장 폴더 아래의 `셀비/프로젝트`에 보관된다. 드라이브가 연결되어 있고 폴더에 쓸 수 있어야 새 프로젝트를 시작할 수 있다.

**설정 → API 키**는 외부 기능을 연결하는 곳이다.

- **Gemini API Key** 또는 **Google Vertex Key**: 영상 분석·대본 작성·상품명 번역·Gemini TTS에 사용한다. 둘 중 하나를 등록할 수 있다. Vertex는 서비스 계정 JSON 파일을 사용하는 별도 인증 방식이다.
- **Fish Audio**: Fish Audio 음성 합성과 목소리 목록에 사용한다. Gemini TTS를 쓴다면 Fish Audio를 반드시 함께 등록해야 하는 것은 아니다.
- **YouTube**: 쇼츠 검색 및 성과 데이터의 읽기 전용 조회에 사용한다.
- **쿠팡 파트너스**: 상품 검색과 제휴 링크 생성에 사용한다. 이미 가진 지원 링크를 직접 붙여넣는 경로와 구분한다.
- **UUP 토큰**: **설정 → UUP 전달**에서 연결한다. 로컬 영상 제작을 시작하기 위한 선행조건은 아니며, UUP에 전달할 때 필요하다.

키를 등록했다는 상태와 연결 테스트를 통과했다는 상태는 다르다. 테스트를 지원하는 공급자는 **연결 테스트**를 실행하고 결과를 확인한다. YouTube·쿠팡은 키 저장 여부를 표시하며 별도의 연결 테스트를 제공하지 않는다.

일반 API 키 카드에는 **이 기기의 보안 저장소에 암호화 보관** 선택이 있다. 끄면 이번 실행에서만 사용한다. 현재 구현은 쿠팡 키에도 이 선택을 제공한다. Google Vertex Key의 지속 보관은 일반 API 키 보안 저장소와 달리 기기의 키 파일 방식이므로 둘을 같은 저장 방식으로 설명하지 않는다. 공급자 사용량·결제·모델 이용 가능 여부는 해당 계정에 따라 달라진다.

## KB-START-005 · 메뉴 구조

왼쪽 작업 메뉴의 역할은 다음과 같다.

- **아이템 찾기**: 기본으로 **인스타 릴스**를 열고 **유튜브 쇼츠**로 전환할 수 있다. 참고 영상과 상품 아이디어를 찾는다.
- **소스 가져오기**: REDnote에서 원본 후보를 찾고 프로젝트에 영상을 담는다.
- **인기 검색어**: 셀비 사용자가 소스 가져오기에서 많이 찾은 검색어를 본다.
- **제작실**: 저장한 프로젝트를 찾고 열거나 새 프로젝트를 시작한다.
- **보관함**: **상품 메모**, **참고 영상**, **수익 링크**를 관리한다.
- **캐러셀**: 영상 프로젝트와 별도의 카드 콘텐츠를 제작한다.
- **설정**: 저장 폴더, 인증정보, 대본·음성 기본값, UUP 및 앱 상태를 관리한다.

진행 중 작업은 작업 트레이에서 확인한다. 다운로드·음성 만들기·렌더·UUP 전달은 각각 진행 상태와 실패 이유를 표시한다. 작업 버튼을 연속해서 누르는 것보다 현재 작업의 상태를 먼저 확인한다.

## KB-START-006 · 첫 프로젝트를 만드는 두 가지 경로

### 안내 흐름으로 시작

1. **제작실 → 새 영상 만들기**를 누른다.
2. 필요한 제작용 키가 비어 있으면 **설정 → API 키**로 이동한다.
3. Gemini 계열 인증과 사용할 음성 엔진의 준비를 마친다.
4. **새 영상 만들기**를 다시 누르면 **소스 가져오기**로 이동한다.
5. 원본을 프로젝트에 담고 **프로젝트 계속하기**로 제작을 이어간다.

### 이미 가진 영상으로 시작

1. **제작실 → 새 프로젝트 시작**을 누른다.
2. 빈 프로젝트의 **영상 준비 → 내 영상 파일**에서 사용할 MP4를 선택한다.
3. 프로젝트 정보와 각 원본의 사용 구간을 정한다.
4. **대본·음성**으로 이동하여 직접 문장을 쓰거나 AI 대본을 생성한다.

**새 영상 만들기**와 **새 프로젝트 시작**은 같은 버튼이 아니다. 앞의 버튼은 AI 제작 준비 여부를 확인하는 안내 입구이고, 뒤의 버튼은 빈 프로젝트를 만든다. 직접 작성한 대본과 **내 음성 파일**을 사용하는 경우 AI 대본·TTS를 호출하지 않는 제작 방식도 가능하다. 로그인·저장 폴더·미디어 도구 등 기본 조건은 여전히 필요하다.

## KB-START-007 · 영상 제작 6단계

1. **영상 준비**: 원본 추가, 순서·사용 구간·원본 음소거, 원본 자막 지우기, 상품·프로젝트 정보 정리.
2. **대본·음성**: 문장 작성, AI 대본 생성, 후킹·구매 안내, 음성 생성 또는 내 음성 파일 연결.
3. **비디오** *(선택)*: 문장에 배치된 장면 확인, 컷·레이어 편집, 디자인 조절.
4. **썸네일** *(선택)*: 표지 준비와 확인.
5. **렌더링**: 준비 상태를 확인하고 완성 영상을 만든다.
6. **배포 준비·UUP 전달**: 완성본과 게시 자료를 확인하고 UUP에 전달한다.

비디오·썸네일 단계는 선택 사항이다. 대본·음성이 준비되면 렌더링으로 진행하는 경로가 있다. 선택 단계를 생략해도 원본·대본·음성·출력의 필수 조건은 충족해야 한다. 단계 이름만 보고 업로드나 실제 게시까지 자동으로 끝났다고 판단하지 않는다.

## KB-START-008 · 저장, 이어서 작업, 제거

프로젝트를 바꾸면 자동 저장 상태를 확인한다. **저장됨**과 저장 실패 안내를 구분한다. 저장 실패 상태에서 앱을 닫거나 프로젝트 폴더를 옮기지 말고 저장 폴더의 연결·권한을 먼저 확인한다.

**제작실**에서 프로젝트명·상품명·진행 단계·차단 사유로 검색할 수 있다. 프로젝트를 선택하고 **계속하기**로 작업을 재개한다. **렌더 오래됨**은 현재 편집 상태와 완성본이 달라졌다는 신호이므로 전달 전에 렌더를 확인한다.

프로젝트 **제거**는 현재 화면에서 별도의 확인 문구를 입력받지 않고 `셀비/복구 보관함`으로 옮긴다. 다운로드 등 작업이 진행 중이면 먼저 끝내거나 취소해야 한다. 복구 보관함은 자동으로 비우지 않는다. **설정 → 화면과 저장 → 복구 보관함 비우기**는 별도 확인 후 영구 삭제하므로, 단순 프로젝트 제거와 구분한다. 앱 안에 원클릭 복원 기능이 있다고 안내하지 않는다.

## KB-START-009 · 자주 묻는 질문

**브라우저만으로 완성 영상을 만들 수 있나요?**

이 문서에서 설명하는 제작 흐름은 데스크톱 앱이다. 웹사이트와 데스크톱 앱을 구분해서 안내한다.

**모든 API 키를 한 번에 등록해야 하나요?**

아니다. 사용할 기능의 키가 필요하다. 다만 **새 영상 만들기** 안내 경로는 AI 제작용 키를 먼저 확인한다. 직접 제작 경로는 KB-START-006을 따른다.

**YouTube나 UUP가 미연결이면 렌더도 못 하나요?**

YouTube는 검색·조회, UUP는 전달에 필요한 연결이다. 원본과 대본·음성, 저장 폴더·제작 도구가 준비된 로컬 제작과 구분한다.

**삭제한 프로젝트가 디스크에 남아 있어요.**

프로젝트 제거가 복구 보관함 이동이기 때문이다. 필요한 파일을 확인한 뒤 별도의 비우기 기능을 사용한다.

## 구현 근거

- `frontend/src/main.ts`: `renderProjects`, `projectResultsMarkup`, `renderHomeSummary`, `renderEnvironmentPane`, `renderPageTabs`, `CREDENTIALS`, `credentialCard`, `credentialStatus`, `start-video`·`new-project`·`delete-project` 동작 처리.
- `frontend/src/state.ts`: `STAGES`, `MAX_PROJECT_SOURCES`.
- `app.go`: `SaveCredential`, `saveCredentialLocked`, `setRememberFlagLocked`, `DeleteProject`, `LoadProject`, `SaveProject`.
- `app_auth.go`: `AccountSession`, `StartGoogleLogin`, `requireAccount`.
- `scripts/publish-release-local.sh`: Windows amd64·macOS arm64 배포 자산 구성.

현재 소스와 그래프의 해당 경로를 대조했다. 그래프의 기록된 누락 없음은 전체 실행 경로의 완전성이나 운영 서비스의 현재 상태를 보증하지 않는다. 다음 문서: [아이템 찾기와 원본](02-discovery-and-sources.md), [대본과 음성](03-script-and-audio.md).