feat: 기상음악 AI 분석 기능 추가

app/(main)/layout.tsx

@@ -7,7 +7,7 @@ import { Header } from "@/widgets/header/ui/header";
 import { AiChatButton } from "@/features/ai-chat/ui/AiChatButton";
 import { AiChatModal } from "@/features/ai-chat/ui/AiChatModal";
 import { useAiChatPanel } from "@/features/ai-chat/model/useAiChatPanel";
-import { WakeUpMusicRecommend } from "@/features/wake-up-music/ui/WakeUpMusicRecommend";
+import { WakeUpMusicRecommend } from "@/features/wake-up-music-recommend/ui/WakeUpMusicRecommend";
 import { RealtimeSubscriptions } from "@/widgets/realtime-subscription/ui/RealtimeSubscriptions";
 
 export default function MainLayout({

app/api/youtube/transcript/route.ts

@@ -0,0 +1,41 @@
+import { HttpStatusCode } from "axios";
+import { NextRequest, NextResponse } from "next/server";
+import { extractYoutubeVideoId } from "@/entities/music/lib/youtube";
+import { getYoutubeTranscript } from "@/entities/music/lib/transcript";
+
+export const runtime = "nodejs";
+
+export async function GET(request: NextRequest) {
+  const authorization = request.headers.get("authorization");
+  const accessToken = authorization?.startsWith("Bearer ")
+    ? authorization.slice("Bearer ".length)
+    : null;
+
+  if (!accessToken) {
+    return NextResponse.json(
+      { error: "access token 없음" },
+      { status: HttpStatusCode.Unauthorized },
+    );
+  }
+
+  const params = request.nextUrl.searchParams;
+  const urlParam = params.get("url");
+  const idParam = params.get("id");
+  const videoId =
+    idParam ?? (urlParam ? extractYoutubeVideoId(urlParam) : null);
+
+  if (!videoId) {
+    return NextResponse.json(
+      { error: "videoId(id) 또는 url이 필요합니다." },
+      { status: HttpStatusCode.BadRequest },
+    );
+  }
+
+  const result = await getYoutubeTranscript(videoId);
+
+  if ("error" in result) {
+    return NextResponse.json(result, { status: HttpStatusCode.NotFound });
+  }
+
+  return NextResponse.json(result);
+}

package.json

@@ -12,6 +12,7 @@
     "format:check": "prettier --check --ignore-unknown ."
   },
   "dependencies": {
+    "@mlc-ai/web-llm": "^0.2.84",
     "@sentry/nextjs": "^10.53.1",
     "@sun-typeface/suit": "^2.0.5",
     "@tanstack/react-query": "^5.90.20",

src/entities/ai/lib/webllm.worker.ts

@@ -0,0 +1,7 @@
+import { WebWorkerMLCEngineHandler } from "@mlc-ai/web-llm";
+
+const handler = new WebWorkerMLCEngineHandler();
+
+self.onmessage = (event: MessageEvent) => {
+  handler.onmessage(event);
+};

src/entities/ai/lib/webllmEngine.ts

@@ -0,0 +1,28 @@
+import type { InitProgressReport, WebWorkerMLCEngine } from "@mlc-ai/web-llm";
+
+export const MUSIC_LLM_MODEL_ID = "gemma-2-2b-it-q4f16_1-MLC";
+
+let enginePromise: Promise<WebWorkerMLCEngine> | null = null;
+
+export function getMusicLlmEngine(
+  onProgress?: (report: InitProgressReport) => void,
+): Promise<WebWorkerMLCEngine> {
+  if (!enginePromise) {
+    enginePromise = (async () => {
+      const { CreateWebWorkerMLCEngine } = await import("@mlc-ai/web-llm");
+      const worker = new Worker(
+        new URL("./webllm.worker.ts", import.meta.url),
+        { type: "module" },
+      );
+
+      return CreateWebWorkerMLCEngine(worker, MUSIC_LLM_MODEL_ID, {
+        initProgressCallback: onProgress,
+      });
+    })().catch((error) => {
+      enginePromise = null;
+      throw error;
+    });
+  }
+
+  return enginePromise;
+}

src/entities/dormitory/lib/musicPermission.ts

@@ -1,11 +1,23 @@
 import type { UserRole } from "@/entities/user/model/user";
 
+// 기자위(DORMITORY_MANAGER) 중 AI 분석을 쓸 수 있는 사감 계정 이름
+const DORM_SUPERVISOR_NAME = "사감선생님";
+
 interface CreateMusicPermissionParams {
   role?: UserRole;
+  name?: string;
 }
 
-export function createMusicPermission({ role }: CreateMusicPermissionParams) {
+export function createMusicPermission({
+  role,
+  name,
+}: CreateMusicPermissionParams) {
+  const isDormManager = role === "DORMITORY_MANAGER";
+
   return {
-    canDeleteAnyMusic: role === "ADMIN" || role === "DORMITORY_MANAGER",
+    canDeleteAnyMusic: role === "ADMIN" || isDormManager,
+    // 어드민은 모두 가능, 기자위는 사감선생님만 가능
+    canUseAiAnalysis:
+      role === "ADMIN" || (isDormManager && name === DORM_SUPERVISOR_NAME),
   };
 }

src/entities/music/api/youtubeQueries.ts

@@ -13,6 +13,10 @@ interface YoutubeVideosResponse {
   videos: YoutubeVideoMetadata[];
 }
 
+export interface YoutubeTranscript {
+  text: string;
+}
+
 export async function getYoutubeVideos(
   videoIds: string[],
   signal?: AbortSignal,
@@ -35,6 +39,25 @@ export async function getYoutubeVideos(
   return Object.fromEntries(data.videos.map((video) => [video.id, video]));
 }
 
+const TRANSCRIPT_TIMEOUT_MS = 65_000;
+
+export async function getYoutubeTranscript(
+  videoId: string,
+  signal?: AbortSignal,
+): Promise<YoutubeTranscript> {
+  const { data } = await instance.get<YoutubeTranscript>(
+    "/api/youtube/transcript",
+    {
+      baseURL: undefined,
+      params: { id: videoId },
+      timeout: TRANSCRIPT_TIMEOUT_MS,
+      signal,
+    },
+  );
+
+  return data;
+}
+
 export const youtubeQueries = {
   videos: (videoIds: string[]) => {
     const ids = Array.from(new Set(videoIds)).sort();
@@ -45,4 +68,13 @@ export const youtubeQueries = {
       enabled: ids.length > 0,
     });
   },
+
+  transcript: (videoId: string) =>
+    queryOptions({
+      queryKey: ["music", "youtube-transcript", videoId],
+      queryFn: ({ signal }) => getYoutubeTranscript(videoId, signal),
+      enabled: Boolean(videoId),
+      staleTime: Infinity,
+      gcTime: Infinity,
+    }),
 } as const;

src/entities/music/lib/transcript.ts

@@ -0,0 +1,164 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export interface YoutubeTranscriptSuccess {
+  text: string;
+}
+
+export interface YoutubeTranscriptFailure {
+  error: string;
+}
+
+export type YoutubeTranscriptResult =
+  | YoutubeTranscriptSuccess
+  | YoutubeTranscriptFailure;
+
+const PREFERRED_LANGS = ["ko", "en"];
+const YT_DLP_CONCURRENCY = Number(process.env.YT_DLP_CONCURRENCY ?? 20);
+const YT_DLP_BIN = process.env.YT_DLP_PATH ?? "yt-dlp";
+const YT_DLP_TIMEOUT_MS = 60_000;
+
+const transcriptCache = new Map<string, string>();
+
+let activeYtDlp = 0;
+const ytDlpWaiters: Array<() => void> = [];
+
+async function withYtDlpLimit<T>(task: () => Promise<T>): Promise<T> {
+  if (activeYtDlp >= YT_DLP_CONCURRENCY) {
+    await new Promise<void>((resolve) => ytDlpWaiters.push(resolve));
+  }
+  activeYtDlp += 1;
+  try {
+    return await task();
+  } finally {
+    activeYtDlp -= 1;
+    ytDlpWaiters.shift()?.();
+  }
+}
+
+function toTimestamp(h: number, m: number, s: number): string {
+  const total = h * 3600 + m * 60 + s;
+  const sec = String(total % 60).padStart(2, "0");
+  const min = Math.floor(total / 60) % 60;
+  const hr = Math.floor(total / 3600);
+  return hr > 0
+    ? `${hr}:${String(min).padStart(2, "0")}:${sec}`
+    : `${min}:${sec}`;
+}
+
+function cleanVtt(vtt: string): string {
+  const entries: string[] = [];
+  let time = "0:00";
+  let previous: string | null = null;
+
+  for (const rawLine of vtt.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (
+      !line ||
+      line.startsWith("WEBVTT") ||
+      line.startsWith("Kind:") ||
+      line.startsWith("Language:") ||
+      /^\d+$/.test(line)
+    ) {
+      continue;
+    }
+
+    const cue = line.match(/^(\d{2}):(\d{2}):(\d{2})[.,]\d+\s*-->/);
+    if (cue) {
+      time = toTimestamp(Number(cue[1]), Number(cue[2]), Number(cue[3]));
+      continue;
+    }
+
+    const text = line.replace(/<[^>]+>/g, "").trim();
+    if (!text || text === previous) continue;
+    entries.push(`[${time}] ${text}`);
+    previous = text;
+  }
+
+  return entries.join("\n");
+}
+
+function langOf(fileName: string): string {
+  return fileName.split(".").at(-2) ?? "";
+}
+
+async function extractViaYtDlp(
+  videoId: string,
+): Promise<YoutubeTranscriptResult> {
+  let workDir: string | null = null;
+  try {
+    workDir = await mkdtemp(path.join(tmpdir(), "yt-transcript-"));
+
+    const args = [
+      "--skip-download",
+      "--write-sub",
+      "--write-auto-sub",
+      "--sub-lang",
+      PREFERRED_LANGS.join(","),
+      "--sub-format",
+      "vtt",
+      "--retries",
+      "3",
+      "--retry-sleep",
+      "5",
+      "--ignore-errors",
+      "--no-abort-on-error",
+      "--sleep-subtitles",
+      "1",
+      "--no-warnings",
+      "-o",
+      path.join(workDir, `${videoId}.%(ext)s`),
+      `https://www.youtube.com/watch?v=${videoId}`,
+    ];
+
+    let rawStderr = "";
+    try {
+      const { stderr } = await execFileAsync(YT_DLP_BIN, args, {
+        timeout: YT_DLP_TIMEOUT_MS,
+      });
+      rawStderr = stderr ?? "";
+    } catch (execError) {
+      const err = execError as { stderr?: string; message?: string };
+      rawStderr = err.stderr ?? err.message ?? String(execError);
+    }
+
+    const files = (await readdir(workDir)).filter((f) => f.endsWith(".vtt"));
+    if (files.length === 0) {
+      return { error: rawStderr.trim() || "자막 파일 없음(원인 미상)" };
+    }
+
+    const preferredFile =
+      PREFERRED_LANGS.map((code) => files.find((f) => langOf(f) === code)).find(
+        Boolean,
+      ) ?? files[0];
+
+    const text = cleanVtt(
+      await readFile(path.join(workDir, preferredFile), "utf-8"),
+    );
+    if (!text) return { error: "yt-dlp: 자막 텍스트가 비어 있습니다." };
+
+    return { text };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  } finally {
+    if (workDir) {
+      await rm(workDir, { recursive: true, force: true }).catch(() => {});
+    }
+  }
+}
+
+export async function getYoutubeTranscript(
+  videoId: string,
+): Promise<YoutubeTranscriptResult> {
+  const cached = transcriptCache.get(videoId);
+  if (cached) return { text: cached };
+
+  const result = await withYtDlpLimit(() => extractViaYtDlp(videoId));
+  if (!("error" in result)) transcriptCache.set(videoId, result.text);
+  return result;
+}