feat: YouTube Live API 연동으로 사용자별 RTMP 송출 대상 도입

[itzjb]

문제

현재 RTMP 송출 대상이 서버 전역 환경변수 하나로 고정되어 있다.

• 키 출처: internal/config/config.go:114 (YOUTUBE_STREAM_KEY)
• 사용 지점: internal/session/manager.go:526-533 — 세션마다 이 하나의 키로 egress 생성
• ingest URL: internal/session/manager.go:30 에 상수 하드코딩
• 클라이언트 UI·REST 어디에도 송출 대상을 지정하는 경로가 없음
• 유튜브 API를 한 번도 호출하지 않는다. RTMP를 밀 뿐이고, 방송이 켜지는 것은 채널 스튜디오 설정의 자동 시작에 의존한다

이 구조에서 파생되는 문제:

1. 사용자별 채널 송출이 불가능하다. 모든 세션이 서버 운영자의 채널 하나로만 나간다.
2. 동시 세션 2개 이상이면 같은 스트림 키로 동시 push되어 충돌한다. 운영 설정은 MAX_SESSIONS=12.
3. 키가 비어 있으면 조건문에 걸려 송출이 조용히 비활성화된다. 실패가 드러나지 않는다.
4. 송출 시작 시점이 트랙 게시 순간으로 고정이라, 사용자가 "오늘은 뷰어에만" 같은 선택을 할 수 없다.

목표

사용자가 자신의 YouTube 계정을 OAuth로 연결하면, 서버가 그 사용자의 토큰으로 방송을 생성하고 ingest 정보를 받아와 해당 세션의 egress에 주입한다. 송출 개시는 명시적 요청으로만 이루어진다.

플랫폼 송출은 opt-in 이다. 연결하지 않은 사용자는 지금과 동일하게 WebRTC 뷰어 경로로만 방송한다.

확정된 설계 결정

1. 명시적 송출 시작 — handleStartStream 501 스텁 실배선

internal/server/server.go:179-186 의 501 스텁과, manager.go:248 에서 idle 로 설정된 뒤 갱신되지 않는 StreamState 를 실제로 배선한다.

근거:

• 실패 가시성 — start가 동기 HTTP이므로 토큰 만료·API 오류를 4xx로 즉답할 수 있다. 자동 시작 구조에서는 실패가 서버 로그에만 남아 사용자가 원인을 알 수 없다.
• 방송 중 제어 — InnoLive 뷰어 송출은 유지한 채 플랫폼 송출만 켜고 끌 수 있어야 한다.
• 스텁이 이미 "트랙 없으면 409" 계약을 갖고 있어(server.go:181-184) 상태 전이 설계 부담이 작다.

계약 변경이지만 위험이 낮은 시점이다. static/client/app.js 는 /stream/start 를 호출하지 않으며(추가 비용은 버튼 1개 + 호출 1건 수준), 전역 키 유실로 현행 자동 송출 동작에 의존하는 사용자가 실존하지 않는다.

2. 방송 라이프사이클 — enableAutoStart / enableAutoStop 사용

liveBroadcasts.insert 시 contentDetails.enableAutoStart=true, enableAutoStop=true 로 생성한다.

transition(live) 는 바인딩된 스트림이 active 여야 하는데, active 는 egress가 프레임을 밀기 시작한 뒤에야 된다. 따라서 transition 을 직접 호출하려면 active 폴링 → 전환 재시도 라는 비동기 상태 머신이 필요하다. autoStart는 이를 제거한다.

부수 효과로 quota 압력이 크게 준다. list 가 1 unit이어도 5초 폴링이면 하루 17,280 units로 기본 한도(10,000)를 넘는다.

포기하는 것은 testing 프리뷰 단계다. fail-closed 설계상 AI 실패 시 검은 프레임이 나가므로 프리뷰의 안전상 가치가 낮다고 판단했다. 필요해지면 enableAutoStart=false + transition 경로를 옵션으로 추가한다.

이 동작은 문서 기재 사항이며 실측 미확인. 착수 전 수동 E2E에서 검증한다.

3. 프로바이더 추상화는 라이프사이클 수준

"스트림 키 조회" 가 아니라 Prepare / Stop 수준으로 추상화한다. YouTube는 Prepare 에서 방송 생성 + bind가 필요하고, 치지직은 키 조회만으로 끝나며 방송 시작/종료 API 자체가 없다. 키 조회 수준으로 추상화하면 두 플랫폼이 한 구조에 들어가지 않는다.

4. 스트림 리소스 프리로딩

liveStreams.insert 시 contentDetails.isReusable=true 로 만들고, OAuth 연결 시점에 1회 생성해 재사용한다. 방송마다는 liveBroadcasts.insert + bind 만 한다.

• 방송당 API 호출 3회 → 2회 (quota 절감, start 응답 단축)
• 연결 직후 ingest 정보가 확보되어 연결 상태 UI를 즉시 표시할 수 있다

5. ingest URL은 API 응답값 — RTMPS 전환

manager.go:30 상수를 제거하고 cdn.ingestionInfo.rtmpsIngestionAddress 를 사용한다. 최종 URL은 문서 명시 규칙에 따라 ingestionAddress + "/" + streamName. 현행 평문 RTMP에서 TLS로 전환되는 보안 개선이 함께 따라온다.

6. 전역 YOUTUBE_STREAM_KEY 제거

폴백으로 남기지 않는다. 유실 후 미복구라 실사용이 0이며, 남기면 "사용자별 송출"과 "서버 전역 송출" 두 경로를 계속 부양해야 한다.

7. OAuth 경로 — connect / callback 2단계

POST /auth/youtube/connect   (XHR, Bearer 인증)
  → 서버가 state 생성·사용자와 바인딩해 저장
  → authorize URL을 JSON으로 반환
클라이언트가 해당 URL로 이동 → 사용자 동의
  → GET /auth/youtube/callback?code=&state=
  → state 대조로 사용자 복원

콜백은 브라우저 리다이렉트로 도착하므로 Authorization 헤더가 없다. state가 유일한 사용자 바인딩 수단이며, 기존 코드에 state 관리 패턴이 없으므로 신규 작성 영역이다.

/auth/* 는 MountAuthHTTPWithServices 가 만드는 별도 mux다. 인증은 handleWithdrawal(internal/auth/account_withdrawal_http.go:20-34)의 인라인 패턴을 따른다. 단 이 패턴은 DB에서 user status active를 확인하지 않으므로, 서비스 계층에서 상태를 확인하거나 authenticateUser 를 핸들러에 주입해 동등하게 맞춘다.

8. Session 내부 구조

egress를 map[provider]*egressJob{egress, cancel, StreamState} 형태로 보관한다. 동시 송출을 지금 구현하지 않아도(1개 제한 정책) 구조가 막지 않고, StreamState 가 provider별로 자연히 분리되며, start 요청 body의 provider 필드가 그대로 키가 된다.

RunTrack(internal/media/track.go:169)은 단일 *RTMPEgress 인자를 유지한다. 동시 송출이 실요구가 되는 시점에 Enqueue 지점(track.go:351)을 fan-out으로 바꾸는 국소 변경으로 확장한다.

동시 송출 도입 시 결정할 것: 출력별 FFmpeg 대 한 FFmpeg의 tee muxer(인코딩 1회, 출력별 격리 상실) 트레이드오프.

9. 스키마

OAuthAccount 에 provider를 추가하지 않고 별도 테이블로 만든다. OAuthAccount 는 로그인 신원이고 송출 연결은 다른 개념이며(로그인 Google 계정과 송출 YouTube 채널이 다를 수 있다), provider enum이 GORM check constraint와 versioned SQL 양쪽에 박혀 있다.

• PK는 별도 UUID, (user_id, provider) 유니크 인덱스
• 멀티 채널은 지금 허용하지 않는다. 허용하면 "이 세션은 어느 채널로 내보내나" 선택 API/UI가 즉시 범위에 편입된다. 나중에 유니크 인덱스를 드롭하고 선택 채널 포인터를 추가하는 마이그레이션으로 연다
• 채널 식별자·채널명은 처음부터 저장 (연결 상태 표시에 당장 필요)
• refresh token 암호화 저장에 internal/auth/provider_token_cipher.go(AES-256-GCM + 키 버전) 재사용. 단 cmd/server/main.go:229-235 에서 Apple 활성 시에만 생성되므로 배선 변경 필요
• 치지직은 ingest URL을 API로 제공하지 않으므로 수동 설정값 자리가 필요하다
• 마이그레이션은 GORM 모델 목록(internal/auth/migrate.go:16-21)과 versioned SQL(000003_*.up/down.sql) 양쪽 모두 갱신한다. 어긋나면 auto 환경과 versioned 환경의 스키마가 달라진다

작업 범위

• 송출 계정 테이블 + 마이그레이션 (GORM + versioned SQL)
• OAuth connect / callback + state 관리
• refresh token 암호화 저장, cipher 배선 조건 수정
• 프로바이더 라이프사이클 인터페이스 + YouTube 구현
• liveStreams.insert(isReusable) 연결 시 1회 생성
• handleStartStream / handleStopStream 실배선, StreamState 갱신
• 사용자별 ingest URL을 egress에 주입
• 전역 YOUTUBE_STREAM_KEY 제거
• 동의 UI (아래 정책 요구사항)
• 클라이언트에 송출 시작/중지 버튼

정책 · 제약

개발자 정책 2개 조항이 직접 걸린다.

1. 사용자 제공 값을 변형해 전송하려면 명시적 동의가 필요하다. 얼굴 비식별화가 여기 해당하므로 동의 UI와 동의 기록이 필요하다.
2. 사용자를 대신한 행위(방송 생성·시작·종료)는 사전 명시 동의와 행위 고지가 요구된다.

할당량: 기본 10,000 units/day. 라이브 메서드별 개별 비용이 공식 문서에 없어 실측이 필요하다. 응답 헤더에는 quota 정보가 없으므로 Cloud Console의 Quotas 페이지 사용량 그래프를 관측한다. 방송 중 생존 판정은 API 폴링이 아니라 로컬 신호(FFmpeg 프로세스 생존, egress 프레임 카운트)로 하고, healthStatus 조회는 분 단위 이상 저빈도로 둔다.

앱 검증: YouTube 스코프는 sensitive 등급(restricted 아님 → CASA 보안평가 면제). 미검증 상태에서는 Testing 100명 + refresh token 7일 만료, 프로덕션 미검증은 누적 100명 상한. 검증에는 도메인 소유권·홈페이지·개인정보처리방침·영어 데모 영상이 필요하며 최대 10일 소요.

계정 요건: 채널 인증 필요, 최초 라이브 활성화에 최대 24시간. 미승인 채널의 토큰으로 호출하면 insufficientPermissions 가 반환되므로 사용자 안내에 활용한다.

서비스 계정 플로우는 Live Streaming API와 비호환이다. 사용자 OAuth + refresh token 보관이 필수다.

구현 시 유의

• refresh token은 계정 × client_id당 100개 한도. 재로그인마다 새로 발급하면 오래된 것부터 무효화되므로 기존 토큰 재사용 또는 명시적 revoke 설계가 필요하다.
• 한 사용자가 다중 세션을 열면 access token 갱신이 경합할 수 있다. internal/auth/refresh_store.go:60-160 의 트랜잭션 + 행 락 패턴을 따르거나 사용자 단위로 직렬화한다.
• 인증 비활성 모드(INNOLIVE_REQUIRE_SESSION_AUTH=false, 벤치마크용)에서는 Session.UserID 가 uuid.Nil 이다. 사용자별 송출 경로는 이 경우를 명시적으로 스킵해야 벤치가 깨지지 않는다.
• 스트림 키는 비밀번호급으로 취급한다. maskStreamKey(internal/media/egress.go:388-394)는 "마지막 / 뒤가 키"라는 형태를 가정하므로, 다른 형태의 URL을 쓰는 플랫폼에서는 마스킹이 뚫린다. 치지직 연동 시 반드시 함께 처리한다.

착수 전 필수

코드 작성 전에 전 과정을 수동으로 1회 재연한다. OAuth Playground(자체 client_id 사용)로 토큰 발급 → curl로 broadcast/stream insert·bind → ffmpeg CLI로 테스트 송출 → active 확인 → complete. 반나절이면 autoStart 실동작·실제 타이밍·quota 소비량이 전부 확인되며, 설계 불확실성이 사실상 해소된다.

관계

• 선행: fix: 트랙 교체 시 RTMP egress가 중단되어 송출이 단절됨 #84 (트랙 교체 시 egress 중단) — 명시적 시작 구조가 성립하려면 egress가 트랙보다 오래 살아야 한다
• 후속: #85 (MAX_SESSIONS 재실측) — 송출이 실제로 켜지면 세션당 FFmpeg가 늘어난다
• 후속: 치지직 연동 (별도 이슈 예정) — 이 이슈에서 만든 기반 위에 확장. 치지직은 방송 생성·시작·종료 API가 없고 ingest URL도 API로 제공되지 않아 이 구조의 부분집합으로 들어온다

[itzjb]

수동 E2E 실증 결과 (2026-08-09) — 가정 1건 반증

코드 작성 전 수동 E2E의 인증 구간을 실행했다. 본문의 가정 하나가 틀렸음이 확인됐다.

🔴 라이브 미활성 감지 조건 정정

본문에 "미승인 채널의 토큰으로 호출하면 insufficientPermissions 가 반환되므로 사용자 안내에 활용한다" 고 적었으나, 실제 응답은 다르다.

라이브 활성화 대기 중인 채널의 토큰으로 liveBroadcasts.insert 호출 시 HTTP 403:

{
  "error": {
    "code": 403,
    "message": "The user is blocked from live streaming.",
    "errors": [{
      "message": "The user is blocked from live streaming.",
      "domain": "youtube.liveBroadcast",
      "reason": "livePermissionBlocked",
      "extendedHelp": "https://support.google.com/youtube/answer/2853834"
    }]
  }
}

• reason 은 insufficientPermissions 가 아니라 livePermissionBlocked
• domain 도 일반 youtube.common 이 아닌 youtube.liveBroadcast
• extendedHelp 에 라이브 활성화 안내 문서 URL이 함께 오므로 사용자 안내 메시지에 그대로 사용 가능

→ 구현의 감지 조건은 reason == "livePermissionBlocked" 로 한다.

남은 불확실성: 이 reason이 "활성화 24시간 대기 중"과 "정책 위반 영구 차단"을 구분해 주는지는 알 수 없다. 활성화 완료 후 같은 호출이 성공하면 "대기 중 = livePermissionBlocked" 로 확정된다.

refresh_token_expires_in 필드 발견

토큰 응답에 문서로 예상하지 못한 필드가 있었다.

expires_in:               3599     (액세스 토큰 1시간)
refresh_token_expires_in: 604799   (정확히 7일)

"Testing 게시 상태에서 리프레시 토큰 7일 만료"가 응답 필드 실물로 확인됐다. 구현 시:

• 토큰 응답 구조체에 이 필드를 받고, 존재하면 만료 시각을 저장·추적해야 한다. 무시하면 7일 뒤 연동이 조용히 죽는다
• Production 게시 전환 시 이 필드가 사라지는지(무기한 전환)는 전환 후 재관측 항목

그 외 구현에 반영할 관찰

• 콜백에 iss=https://accounts.google.com 파라미터가 함께 온다. 문서에 없던 것이므로 콜백 파서는 미지의 쿼리 파라미터에 관대해야 한다
• 인가 code 에 / 가 포함된다. 토큰 교환 시 form-urlencoded 인코딩 필수
• state 왕복 무결성 확인됨. 요청 스코프가 부분 승인 없이 그대로 부여됨
• channels.list(mine=true) 는 totalResults=1 로 채널에 정확히 매핑됐다. 다만 구현은 items 빈 배열(채널이 없는 Google 계정으로 연결 시도) 케이스를 에러로 다뤄야 한다 — 실제로 발생 가능한 사용자 시나리오다

[itzjb]

수동 E2E 후반부 실측 결과 (2026-08-10)

채널 라이브 활성화 완료 후 전 단계를 실행했다. 테스트 방송은 privacyStatus=private 으로 생성했고 종료 후 삭제했다.

✅ enableAutoStart / enableAutoStop 실동작 확정 — 설계 유효

transition 을 한 번도 호출하지 않고 방송이 라이브로 전환됐다. 폴링 2.5초 간격 타임라인:

t=0.0s   ffmpeg 송출 시작
t=5.5s   streamStatus:    ready → inactive        (연결 초기 과도 상태)
t=9.7s   streamStatus:    inactive → active
t=9.7s   lifeCycleStatus: ready → liveStarting
t=13.7s  lifeCycleStatus: liveStarting → live     ← transition 호출 0회
t=13.7s  healthStatus:    {"status": "good"}

종료 시:

t=7.5s   streamStatus:    active → inactive
t=57.6s  lifeCycleStatus: live → complete         ← enableAutoStop 자동 전환

비동기 상태 머신이 불필요하다는 결론이 유지된다.

구현 시 참고:

• streamStatus 는 ready → inactive → active 로 출렁인다. active 만 종단 신호로 쓸 것 (inactive 를 실패로 해석하면 안 됨)
• lifeCycleStatus 에 liveStarting 중간 단계가 실재한다
• healthStatus 는 문제가 없으면 configurationIssues 필드 자체가 생략된다
• 송출 중지 후 YouTube 측 종료 반영에 약 1분이 걸린다. 사용자 안내 또는 비동기 1회 확인이 필요하다

✅ livePermissionBlocked 가설 확정

어제 403 livePermissionBlocked 였던 liveBroadcasts.insert 가 활성화 완료 후 오늘 200으로 성공했다. livePermissionBlocked = "라이브 활성화 대기 중" 이 확정됐고, 구현의 감지 조건이 옳다는 것이 검증됐다.

lifeCycleStatus 초기값은 created 이며, bind 호출이 created → ready 전이를 만든다.

cdn.ingestionInfo 실물 — 5필드 전부 수신

streamName:                  <24자>
ingestionAddress:            rtmp://a.rtmp.youtube.com/live2
backupIngestionAddress:      rtmp://b.rtmp.youtube.com/live2?backup=1
rtmpsIngestionAddress:       rtmps://a.rtmps.youtube.com/live2
rtmpsBackupIngestionAddress: rtmps://b.rtmps.youtube.com/live2?backup=1

• ⚠️ rtmpsIngestionAddress 에 :443 포트 표기가 없다. 조사 문서의 rtmps://...:443/live2 서술과 다르다. URL 조합 코드는 실물 기준으로 작성할 것
• ingestionAddress 가 현행 manager.go:30 상수와 일치한다(끝 슬래시 유무만 차이). 상수를 API 응답값으로 대체해도 회귀가 없다는 방증
• liveStreams.insert 응답의 status.streamStatus 초기값은 ready 다(inactive 아님)
• contentDetails.isReusable=true 반영 확인. 생성한 재사용 스트림은 보존해 두었으므로 다음 테스트에서 "연결 시 1회 생성 후 재사용" 시나리오를 검증할 수 있다

🔴 리프레시 토큰 만료는 갱신으로 연장되지 않는다

토큰 갱신(2026-08-10 09:14) 응답:

• 새 refresh_token 이 오지 않는다 (필드 자체 부재). Google 표준 동작이며, 회전 저장 로직은 방어용으로만 유효하다
• refresh_token_expires_in: 505053 — 최초 발급 시의 604799에서 리셋되지 않고 감소했다. 차이 99,746초는 최초 발급(2026-08-09 05:31)부터의 경과 시간과 일치한다

운영 결론: Testing 게시 상태인 한 주기적 갱신으로 리프레시 토큰을 연장할 수 없다. 2026-08-09 발급분은 2026-08-16 05:31에 만료되며, 그 시점에 연동이 끊긴다.

대응 선택지:

1. 데모 전 재연결 (7일 이내). 간단하지만 잊으면 당일 사고
2. Production 게시로 전환 — 7일 만료는 문서상 Testing 게시 상태에 결부된 제약이므로, Production(미검증)으로 전환하면 사라질 가능성이 있다. 대가는 미검증 앱 경고 화면과 프로젝트 수명 누적 신규 사용자 100명 상한이다. 검증 절차 없이도 가능하므로 확인 가치가 크다 — 전환 후 재동의해 응답의 refresh_token_expires_in 유무를 보면 즉시 판별된다
3. 앱 검증 완료 후 Production — 근본 해결이나 도메인 소유권·홈페이지·개인정보처리방침·영어 데모 영상이 필요하고 최대 10일이 걸린다