@hed-hog/lms 0.0.361 → 0.0.365

package/src/course/course-video-hls.service.ts

@@ -0,0 +1,946 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import { FileService, NotificationService, SettingService } from '@hed-hog/core';
+import { IJobHandler, QueueHandlerRegistry, QueueJobService } from '@hed-hog/queue';
+import {
+  BadRequestException,
+  Inject,
+  Injectable,
+  Logger,
+  NotFoundException,
+  OnModuleInit,
+  forwardRef,
+} from '@nestjs/common';
+import { execFile } from 'child_process';
+import { existsSync, promises as fs, readdirSync } from 'fs';
+import { tmpdir } from 'os';
+import { basename, join } from 'path';
+import { promisify } from 'util';
+
+export const LMS_VIDEO_HLS_JOB = 'lms.video.hls';
+
+const execFileAsync = promisify(execFile);
+
+type HlsVariantConfig = {
+  variantIndex: number;
+  height: number;
+  width: number;
+  videoBitrate: string;
+  audioBitrate: string;
+  bandwidth: number;
+};
+
+type LessonFrameResult = {
+  fileId: number;
+  timeSeconds: number;
+  outputBytes: number;
+};
+
+type NotificationContext = {
+  userId: number;
+  notificationId: number;
+};
+
+const HLS_LADDER_PRESETS: Record<number, { width: number; height: number; videoBitrate: string; audioBitrate: string; bandwidth: number }> = {
+  480:  { width: 854,  height: 480,  videoBitrate: '1500k', audioBitrate: '96k',  bandwidth: 1500000  },
+  720:  { width: 1280, height: 720,  videoBitrate: '2800k', audioBitrate: '128k', bandwidth: 2800000  },
+  1080: { width: 1920, height: 1080, videoBitrate: '5000k', audioBitrate: '192k', bandwidth: 5000000  },
+};
+
+@Injectable()
+export class CourseVideoHlsService implements OnModuleInit, IJobHandler {
+  private readonly logger = new Logger(CourseVideoHlsService.name);
+
+  constructor(
+    @Inject(forwardRef(() => PrismaService))
+    private readonly prisma: PrismaService,
+    @Inject(forwardRef(() => FileService))
+    private readonly fileService: FileService,
+    @Inject(forwardRef(() => SettingService))
+    private readonly settingService: SettingService,
+    @Inject(forwardRef(() => NotificationService))
+    private readonly notificationService: NotificationService,
+    @Inject(forwardRef(() => QueueHandlerRegistry))
+    private readonly registry: QueueHandlerRegistry,
+    @Inject(forwardRef(() => QueueJobService))
+    private readonly queueJob: QueueJobService,
+  ) {}
+
+  onModuleInit() {
+    this.registry.register(LMS_VIDEO_HLS_JOB, this);
+    this.logger.log(`Registered handler for "${LMS_VIDEO_HLS_JOB}"`);
+  }
+
+  async enqueueHls(params: {
+    userId: number;
+    courseId: number;
+    sessionId: number;
+    lessonId: number;
+    originalFileId: number;
+  }) {
+    const lesson = await (this.prisma as any).course_lesson.findFirst({
+      where: {
+        id: params.lessonId,
+        course_module_id: params.sessionId,
+        course_module: { course_id: params.courseId },
+      },
+      include: { course_module: true },
+    });
+
+    if (!lesson) throw new NotFoundException('Lesson not found for this course session');
+
+    const content = this.parseContent(lesson.content);
+    if (lesson.type !== 'video' || content?.sourceType !== 'video') {
+      throw new BadRequestException('HLS processing is only available for video lessons');
+    }
+
+    if (content?.videoProvedor !== 'file_storage') {
+      throw new BadRequestException('HLS processing requires File Storage provider');
+    }
+
+    const original = await (this.prisma as any).file.findUnique({
+      where: { id: params.originalFileId },
+      include: { file_mimetype: true },
+    });
+
+    if (!original) throw new NotFoundException('Original video file not found');
+
+    const mimetype = original.file_mimetype?.name ?? '';
+    if (!this.isVideoFile(mimetype, original.filename)) {
+      throw new BadRequestException('Original file must be a video');
+    }
+
+    await this.upsertLessonFile({
+      lessonId: params.lessonId,
+      type: 'video_original',
+      fileId: params.originalFileId,
+      title: original.filename ?? `Original video ${params.originalFileId}`,
+      public: false,
+      overwrite: true,
+    });
+
+    const asyncNotification = await this.notificationService.create({
+      user_id: params.userId,
+      title: 'Geração de HLS em andamento',
+      body: 'Preparando pipeline de processamento HLS do vídeo...',
+      type: 'progress' as any,
+      progress: 1,
+      started_at: new Date().toISOString(),
+      auto_remove: false,
+      action_type: 'url' as any,
+      action_url: '/queue/jobs',
+      action_data: {
+        source: 'lms-video-hls',
+        courseId: params.courseId,
+        lessonId: params.lessonId,
+      },
+    });
+
+    const job = await this.queueJob.enqueue({
+      type: LMS_VIDEO_HLS_JOB,
+      queueName: LMS_VIDEO_HLS_JOB,
+      payload: {
+        courseId: params.courseId,
+        sessionId: params.sessionId,
+        lessonId: params.lessonId,
+        originalFileId: params.originalFileId,
+        notificationId: asyncNotification.id,
+        notificationUserId: params.userId,
+      },
+      sourceModule: 'lms',
+      sourceEntity: 'course_lesson',
+      sourceEntityId: String(params.lessonId),
+      maxAttempts: 3,
+    });
+
+    await (this.prisma as any).notification.update({
+      where: { id: asyncNotification.id },
+      data: {
+        action_data: {
+          source: 'lms-video-hls',
+          courseId: params.courseId,
+          lessonId: params.lessonId,
+          queueJobId: job.id,
+        },
+      },
+    });
+
+    await (this.prisma as any).course_lesson.update({
+      where: { id: params.lessonId },
+      data: {
+        content: JSON.stringify({
+          ...(content ?? {}),
+          sourceType: 'video',
+          videoConversionJobId: job.id,
+        }),
+      },
+    });
+
+    return { queueJobId: job.id, status: 'queued' };
+  }
+
+  async handle(job: {
+    id: number;
+    type: string;
+    queue_name: string;
+    payload: Record<string, any>;
+    attempts: number;
+    max_attempts: number;
+    source_module?: string | null;
+    source_entity?: string | null;
+    source_entity_id?: string | null;
+  }): Promise<any> {
+    const { courseId, sessionId, lessonId, originalFileId } = job.payload as {
+      courseId?: number;
+      sessionId?: number;
+      lessonId?: number;
+      originalFileId?: number;
+    };
+
+    const notificationContext: NotificationContext | undefined =
+      Number.isInteger(Number(job.payload?.notificationId)) &&
+      Number.isInteger(Number(job.payload?.notificationUserId))
+        ? { notificationId: Number(job.payload.notificationId), userId: Number(job.payload.notificationUserId) }
+        : undefined;
+
+    const emitProgress = async (message: string, metadata?: Record<string, unknown>) => {
+      await this.createProgressEvent(job.id, message, metadata, notificationContext);
+    };
+
+    if (!courseId || !sessionId || !lessonId || !originalFileId) {
+      throw new Error('Invalid LMS HLS job payload');
+    }
+
+    this.logger.debug(`[HLS job=${job.id}] payload OK — courseId=${courseId} lessonId=${lessonId} originalFileId=${originalFileId} attempt=${job.attempts}/${job.max_attempts}`);
+
+    const maxInputBytes = this.getPositiveIntegerEnv('LMS_VIDEO_MAX_INPUT_BYTES');
+    const ffmpegTimeoutMs = this.getPositiveIntegerEnv('LMS_VIDEO_FFMPEG_TIMEOUT_MS') ?? 1000 * 60 * 60 * 2;
+
+    this.logger.debug(`[HLS job=${job.id}] loading settings...`);
+    const settings = await this.settingService.getSettingValues([
+      'lms-hls-resolutions',
+      'lms-hls-segment-duration',
+      'lms-video-frame-capture-interval-seconds',
+      'lms-image-extraction-enabled',
+      'lms-audio-transcription-enabled',
+    ]);
+    this.logger.debug(`[HLS job=${job.id}] settings loaded — resolutions=${settings['lms-hls-resolutions']} segmentDuration=${settings['lms-hls-segment-duration']}`);
+
+    const hlsResolutions = this.parseResolutions(settings['lms-hls-resolutions']);
+    const segmentDuration = Math.max(2, Number(settings['lms-hls-segment-duration'] || 6));
+    const imageExtractionEnabled = settings['lms-image-extraction-enabled'] !== false;
+    const transcriptionEnabled = settings['lms-audio-transcription-enabled'] !== false;
+    const frameIntervalSeconds = this.resolveFrameIntervalSeconds(settings['lms-video-frame-capture-interval-seconds']);
+
+    this.logger.debug(`[HLS job=${job.id}] resolutions=${hlsResolutions.join(',')} segmentDuration=${segmentDuration}s imageExtraction=${imageExtractionEnabled} transcription=${transcriptionEnabled}`);
+
+    const workDir = await fs.mkdtemp(join(tmpdir(), `lms-hls-${job.id}-`));
+    const inputPath = join(workDir, `original-${originalFileId}.mp4`);
+    const hlsOutDir = join(workDir, 'hls');
+    await fs.mkdir(hlsOutDir, { recursive: true });
+
+    this.logger.debug(`[HLS job=${job.id}] workDir=${workDir}`);
+
+    const jobStartedAt = Date.now();
+
+    this.logger.log(`Queue job ${job.id}: starting HLS generation (lesson=${lessonId})`);
+    await emitProgress('Baixando vídeo original...', { phase: 'download_original', lessonId });
+
+    this.logger.debug(`[HLS job=${job.id}] downloading original file ${originalFileId} to ${inputPath}...`);
+    const downloaded = await this.fileService.downloadToPath(
+      originalFileId,
+      inputPath,
+      maxInputBytes ? { maxBytes: maxInputBytes } : undefined,
+    );
+    const inputSizeMb = parseFloat((downloaded.size / (1024 * 1024)).toFixed(2));
+    this.logger.debug(`[HLS job=${job.id}] download complete — ${inputSizeMb} MB in ${Date.now() - jobStartedAt}ms`);
+
+    await emitProgress(`Vídeo baixado (${inputSizeMb} MB). Lendo dimensões e duração...`, {
+      phase: 'probe_duration',
+      lessonId,
+      inputSizeMb,
+    });
+
+    let probedDuration: number | null = null;
+    try {
+      this.logger.debug(`[HLS job=${job.id}] probing duration...`);
+      probedDuration = await this.probeDurationSeconds(inputPath, ffmpegTimeoutMs);
+      this.logger.debug(`[HLS job=${job.id}] duration=${probedDuration}s`);
+      if (probedDuration !== null && probedDuration > 0) {
+        await (this.prisma as any).course_lesson.update({
+          where: { id: lessonId },
+          data: { duration_seconds: probedDuration },
+        });
+      }
+    } catch (err: any) {
+      this.logger.warn(`Queue job ${job.id}: failed to probe duration: ${err?.message ?? err}`);
+    }
+
+    this.logger.debug(`[HLS job=${job.id}] probing source height...`);
+    const sourceHeight = await this.probeVideoHeight(inputPath);
+    this.logger.debug(`[HLS job=${job.id}] sourceHeight=${sourceHeight ?? 'unknown'}`);
+    const variants = this.buildHlsVariants(hlsResolutions, sourceHeight);
+
+    if (variants.length === 0) {
+      throw new Error(`No suitable HLS variants for source height ${sourceHeight ?? 'unknown'}`);
+    }
+
+    this.logger.log(`Queue job ${job.id}: building HLS with variants: ${variants.map((v) => v.height + 'p').join(', ')}`);
+    this.logger.debug(`[HLS job=${job.id}] ffmpeg encode starting — variants=${variants.map((v) => `${v.height}p@${v.videoBitrate}`).join(', ')} segmentDuration=${segmentDuration}s outDir=${hlsOutDir}`);
+    await emitProgress(`Gerando HLS (${variants.map((v) => v.height + 'p').join(', ')})...`, {
+      phase: 'hls_encode',
+      lessonId,
+      variants: variants.map((v) => v.height),
+    });
+
+    const encodeStart = Date.now();
+    await this.generateHls({ inputPath, outDir: hlsOutDir, variants, segmentDuration, timeoutMs: ffmpegTimeoutMs });
+    this.logger.debug(`[HLS job=${job.id}] ffmpeg encode complete in ${Date.now() - encodeStart}ms`);
+
+    // Count generated segments to log
+    let totalSegmentCount = 0;
+    for (const v of variants) {
+      const variantDir = join(hlsOutDir, `stream_${v.variantIndex}`);
+      const files = (await fs.readdir(variantDir)).filter((f) => f.endsWith('.ts'));
+      this.logger.debug(`[HLS job=${job.id}] variant stream_${v.variantIndex} (${v.height}p): ${files.length} segments`);
+      totalSegmentCount += files.length;
+    }
+    this.logger.debug(`[HLS job=${job.id}] total segments to upload: ${totalSegmentCount} across ${variants.length} variants`);
+
+    await emitProgress('HLS gerado. Enviando arquivos para storage...', {
+      phase: 'hls_upload',
+      lessonId,
+    });
+
+    this.logger.debug(`[HLS job=${job.id}] starting upload of ${totalSegmentCount} segments + ${variants.length} playlists + 1 master`);
+    const uploadStart = Date.now();
+    const masterManifestFileId = await this.uploadHlsDirectory({
+      lessonId,
+      hlsOutDir,
+      variants,
+      emitProgress,
+    });
+    this.logger.debug(`[HLS job=${job.id}] upload complete in ${Date.now() - uploadStart}ms — masterFileId=${masterManifestFileId}`);
+
+    this.logger.debug(`[HLS job=${job.id}] upserting video_hls lesson file...`);
+    await this.upsertLessonFile({
+      lessonId,
+      type: 'video_hls',
+      fileId: masterManifestFileId,
+      title: 'HLS Stream',
+      public: false,
+      overwrite: true,
+    });
+
+    this.logger.log(`Queue job ${job.id}: HLS uploaded for lesson ${lessonId} (masterFileId=${masterManifestFileId})`);
+
+    let frameResults: LessonFrameResult[] = [];
+
+    try {
+      if (imageExtractionEnabled) {
+        this.logger.debug(`[HLS job=${job.id}] starting frame extraction — interval=${frameIntervalSeconds}s`);
+        await emitProgress('Extraindo imagens do vídeo...', { phase: 'extract_frames', lessonId });
+        const frameStart = Date.now();
+        frameResults = await this.extractAndUploadLessonFrames({
+          jobId: job.id,
+          lessonId,
+          inputPath,
+          workDir,
+          intervalSeconds: frameIntervalSeconds,
+          timeoutMs: ffmpegTimeoutMs,
+        });
+        this.logger.debug(`[HLS job=${job.id}] frame extraction done — ${frameResults.length} frames in ${Date.now() - frameStart}ms`);
+        await emitProgress(
+          frameResults.length > 0
+            ? `Imagens extraídas com sucesso (${frameResults.length}).`
+            : 'Nenhuma imagem foi extraída do vídeo.',
+          { phase: 'extract_frames_done', lessonId, frames: frameResults.length },
+        );
+      } else {
+        this.logger.debug(`[HLS job=${job.id}] frame extraction disabled — skipping`);
+      }
+
+      if (transcriptionEnabled) {
+        this.logger.debug(`[HLS job=${job.id}] starting audio extraction for transcription`);
+        await emitProgress('Extraindo áudio do vídeo...', { phase: 'extract_audio', lessonId });
+        const audioFileId = await this.extractAndUploadLessonAudio({
+          courseId,
+          lessonId,
+          localInputPath: inputPath,
+          tempDir: workDir,
+        });
+
+        if (audioFileId) {
+          this.logger.debug(`[HLS job=${job.id}] audio extracted — fileId=${audioFileId}, enqueuing transcription`);
+          await emitProgress('Áudio extraído. Agendando transcrição...', {
+            phase: 'queue_transcription',
+            lessonId,
+            audioFileId,
+          });
+          const transcriptionJob = await this.queueJob.enqueue({
+            type: 'lms.audio.transcribe',
+            queueName: 'lms.audio.transcribe',
+            payload: {
+              courseId,
+              sessionId,
+              lessonId,
+              audioFileId,
+              parentJobId: job.id,
+              notificationId: notificationContext?.notificationId,
+              notificationUserId: notificationContext?.userId,
+            },
+            maxAttempts: 3,
+          });
+          await emitProgress(`Transcrição agendada no job #${transcriptionJob.id}.`, {
+            phase: 'queue_transcription_done',
+            lessonId,
+            transcriptionJobId: transcriptionJob.id,
+          });
+
+          this.logger.debug(`[HLS job=${job.id}] transcription job enqueued — transcriptionJobId=${transcriptionJob.id}`);
+          const totalMs = Date.now() - jobStartedAt;
+          this.logger.log(`[HLS job=${job.id}] pipeline complete in ${totalMs}ms — lessonId=${lessonId} masterFileId=${masterManifestFileId} frames=${frameResults.length} transcriptionJob=${transcriptionJob.id}`);
+          return {
+            lessonId,
+            probedDurationSeconds: probedDuration,
+            masterManifestFileId,
+            variants: variants.length,
+            extractedFrames: frameResults.length,
+            transcriptionJobId: transcriptionJob.id,
+            totalMs,
+          };
+        } else {
+          this.logger.debug(`[HLS job=${job.id}] audio extraction returned no file — skipping transcription`);
+          await emitProgress('Áudio não disponível. Encerrando pipeline sem transcrição.', {
+            phase: 'queue_transcription_skipped',
+            lessonId,
+          });
+        }
+      }
+    } catch (error) {
+      this.logger.error(`[HLS job=${job.id}] pipeline FAILED after ${Date.now() - jobStartedAt}ms — ${error instanceof Error ? error.stack : String(error)}`);
+      if (notificationContext) {
+        const message = error instanceof Error ? error.message : 'Falha no pipeline HLS.';
+        await this.updateAsyncNotification(notificationContext, 100, `Falha: ${message}`, false);
+      }
+      throw error;
+    } finally {
+      this.logger.debug(`[HLS job=${job.id}] cleaning workDir ${workDir}`);
+      await fs.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
+      this.logger.log(`Queue job ${job.id}: cleaned temporary folder ${workDir}`);
+    }
+
+    if (notificationContext) {
+      await this.updateAsyncNotification(notificationContext, 100, 'HLS gerado com sucesso.', true);
+    }
+
+    const totalMs = Date.now() - jobStartedAt;
+    this.logger.log(`[HLS job=${job.id}] pipeline complete in ${totalMs}ms — lessonId=${lessonId} masterFileId=${masterManifestFileId} frames=${frameResults.length} transcription=skipped`);
+    return {
+      lessonId,
+      probedDurationSeconds: probedDuration,
+      masterManifestFileId,
+      variants: variants.length,
+      extractedFrames: frameResults.length,
+      transcriptionJobId: null,
+      totalMs,
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // HLS Generation
+  // ---------------------------------------------------------------------------
+
+  private async generateHls(params: {
+    inputPath: string;
+    outDir: string;
+    variants: HlsVariantConfig[];
+    segmentDuration: number;
+    timeoutMs: number;
+  }) {
+    const { inputPath, outDir, variants, segmentDuration, timeoutMs } = params;
+    const ffmpegCmd = this.getFfmpegCommand();
+
+    // Create output directories for each variant
+    for (const v of variants) {
+      await fs.mkdir(join(outDir, `stream_${v.variantIndex}`), { recursive: true });
+    }
+
+    const args: string[] = ['-y', '-i', inputPath];
+
+    if (variants.length > 1) {
+      args.push('-filter_complex', `[0:v]split=${variants.length}${variants.map((v) => `[v${v.variantIndex}]`).join('')}`);
+      for (const v of variants) {
+        args.push(
+          `-map`, `[v${v.variantIndex}]`,
+          `-map`, `0:a:0`,
+          `-c:v:${v.variantIndex}`, `libx264`,
+          `-b:v:${v.variantIndex}`, v.videoBitrate,
+          `-s:v:${v.variantIndex}`, `${v.width}x${v.height}`,
+          `-c:a:${v.variantIndex}`, `aac`,
+          `-b:a:${v.variantIndex}`, v.audioBitrate,
+        );
+      }
+      args.push('-var_stream_map', variants.map((v) => `v:${v.variantIndex},a:${v.variantIndex}`).join(' '));
+    } else {
+      const v = variants[0]!;
+      args.push(
+        `-c:v`, `libx264`,
+        `-b:v`, v.videoBitrate,
+        `-s`, `${v.width}x${v.height}`,
+        `-c:a`, `aac`,
+        `-b:a`, v.audioBitrate,
+        `-var_stream_map`, `v:0,a:0`,
+      );
+    }
+
+    args.push(
+      `-master_pl_name`, `master.m3u8`,
+      `-f`, `hls`,
+      `-hls_time`, String(segmentDuration),
+      `-hls_list_size`, `0`,
+      `-hls_segment_filename`, join(outDir, 'stream_%v', 'seg%03d.ts'),
+      join(outDir, 'stream_%v', 'playlist.m3u8'),
+    );
+
+    try {
+      await execFileAsync(ffmpegCmd, args, {
+        maxBuffer: 1024 * 1024 * 20,
+        timeout: timeoutMs,
+        windowsHide: true,
+      });
+    } catch (error: any) {
+      if (error?.code === 'ENOENT') {
+        throw new Error(`FFmpeg binary not found at "${ffmpegCmd}"`);
+      }
+      if (error?.killed && error?.signal === 'SIGTERM') {
+        throw new Error(`FFmpeg HLS generation timed out after ${timeoutMs}ms`);
+      }
+      throw error;
+    }
+  }
+
+  private async uploadHlsDirectory(params: {
+    lessonId: number;
+    hlsOutDir: string;
+    variants: HlsVariantConfig[];
+    emitProgress: (message: string, metadata?: Record<string, unknown>) => Promise<void>;
+  }): Promise<number> {
+    const { lessonId, hlsOutDir, variants, emitProgress } = params;
+
+    // Upload all segment files in batches
+    const BATCH_SIZE = 20;
+    const segmentUploads: Array<{ localPath: string; location: string; filename: string }> = [];
+
+    for (const v of variants) {
+      const variantDir = join(hlsOutDir, `stream_${v.variantIndex}`);
+      const files = await fs.readdir(variantDir);
+
+      for (const filename of files) {
+        if (filename === 'playlist.m3u8') continue; // upload manifests separately
+        segmentUploads.push({
+          localPath: join(variantDir, filename),
+          location: `lms/lessons/hls/${lessonId}/stream_${v.variantIndex}`,
+          filename,
+        });
+      }
+    }
+
+    const totalBatches = Math.ceil(segmentUploads.length / BATCH_SIZE);
+    this.logger.debug(`[HLS upload lessonId=${lessonId}] ${segmentUploads.length} segments → ${totalBatches} batches of ${BATCH_SIZE}`);
+
+    for (let i = 0; i < segmentUploads.length; i += BATCH_SIZE) {
+      const batch = segmentUploads.slice(i, i + BATCH_SIZE);
+      const batchIndex = Math.floor(i / BATCH_SIZE) + 1;
+      const batchStart = Date.now();
+      this.logger.debug(`[HLS upload lessonId=${lessonId}] batch ${batchIndex}/${totalBatches} — uploading ${batch.map((s) => s.filename).join(', ')}`);
+      await Promise.all(
+        batch.map((seg) =>
+          this.fileService.uploadFromPath(seg.location, seg.localPath, {
+            originalname: seg.filename,
+            mimetype: 'video/MP2T',
+          }),
+        ),
+      );
+      this.logger.debug(`[HLS upload lessonId=${lessonId}] batch ${batchIndex}/${totalBatches} done in ${Date.now() - batchStart}ms`);
+      await emitProgress(
+        `Enviando segmentos HLS... (${batchIndex}/${totalBatches})`,
+        { phase: 'hls_upload', lessonId, batchIndex, totalBatches },
+      );
+    }
+
+    // Upload variant playlists
+    for (const v of variants) {
+      const playlistPath = join(hlsOutDir, `stream_${v.variantIndex}`, 'playlist.m3u8');
+      this.logger.debug(`[HLS upload lessonId=${lessonId}] uploading playlist stream_${v.variantIndex}/playlist.m3u8`);
+      await this.fileService.uploadFromPath(
+        `lms/lessons/hls/${lessonId}/stream_${v.variantIndex}`,
+        playlistPath,
+        { originalname: 'playlist.m3u8', mimetype: 'application/x-mpegURL' },
+      );
+      this.logger.debug(`[HLS upload lessonId=${lessonId}] playlist stream_${v.variantIndex} uploaded`);
+    }
+
+    // Upload master manifest last, keep its file ID
+    const masterPath = join(hlsOutDir, 'master.m3u8');
+    this.logger.debug(`[HLS upload lessonId=${lessonId}] uploading master.m3u8`);
+    const masterFile = await this.fileService.uploadFromPath(
+      `lms/lessons/hls/${lessonId}`,
+      masterPath,
+      { originalname: 'master.m3u8', mimetype: 'application/x-mpegURL' },
+    );
+    this.logger.debug(`[HLS upload lessonId=${lessonId}] master.m3u8 uploaded — fileId=${masterFile.id}`);
+
+    return masterFile.id;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Ladder helpers
+  // ---------------------------------------------------------------------------
+
+  private parseResolutions(raw: unknown): number[] {
+    const str = typeof raw === 'string' ? raw : '480,720,1080';
+    const parsed = str
+      .split(',')
+      .map((s) => parseInt(s.trim(), 10))
+      .filter((n) => !isNaN(n) && HLS_LADDER_PRESETS[n] !== undefined);
+    return parsed.length > 0 ? [...new Set(parsed)].sort((a, b) => a - b) : [480, 720, 1080];
+  }
+
+  private buildHlsVariants(resolutions: number[], sourceHeight: number | null): HlsVariantConfig[] {
+    const effective = resolutions.filter((h) => sourceHeight === null || h <= sourceHeight);
+    // Always include at least the lowest quality or the source if it's below all configured resolutions
+    if (effective.length === 0 && sourceHeight !== null) {
+      const closest = resolutions.reduce((prev, curr) =>
+        Math.abs(curr - sourceHeight) < Math.abs(prev - sourceHeight) ? curr : prev,
+      );
+      effective.push(closest);
+    }
+    return effective.map((height, idx) => {
+      const preset = HLS_LADDER_PRESETS[height]!;
+      return { variantIndex: idx, height, ...preset };
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // FFprobe helpers
+  // ---------------------------------------------------------------------------
+
+  private async probeVideoHeight(inputPath: string): Promise<number | null> {
+    const ffprobeCmd = this.getFfprobeCommand();
+    try {
+      const { stdout } = await execFileAsync(
+        ffprobeCmd,
+        ['-v', 'error', '-select_streams', 'v:0', '-show_entries', 'stream=height', '-of', 'default=noprint_wrappers=1:nokey=1', inputPath],
+        { maxBuffer: 1024 * 1024, timeout: 30_000, windowsHide: true },
+      );
+      const h = parseInt(stdout.trim(), 10);
+      return Number.isFinite(h) && h > 0 ? h : null;
+    } catch {
+      return null;
+    }
+  }
+
+  private async probeDurationSeconds(inputPath: string, timeoutMs: number): Promise<number | null> {
+    const ffprobeCmd = this.getFfprobeCommand();
+    try {
+      const { stdout } = await execFileAsync(
+        ffprobeCmd,
+        ['-v', 'error', '-show_entries', 'format=duration', '-of', 'default=noprint_wrappers=1:nokey=1', inputPath],
+        { maxBuffer: 1024 * 1024, timeout: Math.min(timeoutMs, 30_000), windowsHide: true },
+      );
+      const parsed = parseFloat(stdout.trim());
+      return Number.isFinite(parsed) && parsed > 0 ? Math.round(parsed) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Frame extraction (same logic as CourseVideoConversionService)
+  // ---------------------------------------------------------------------------
+
+  private async extractAndUploadLessonFrames(params: {
+    jobId: number;
+    lessonId: number;
+    inputPath: string;
+    workDir: string;
+    intervalSeconds: number;
+    timeoutMs: number;
+  }): Promise<LessonFrameResult[]> {
+    const intervalSeconds = Math.max(1, Math.floor(params.intervalSeconds));
+    const framesDir = join(params.workDir, 'frames');
+    await fs.mkdir(framesDir, { recursive: true });
+
+    const pattern = join(framesDir, 'frame-%08d.jpg');
+    const ffmpegCmd = this.getFfmpegCommand();
+
+    try {
+      await execFileAsync(
+        ffmpegCmd,
+        ['-y', '-i', params.inputPath, '-vf', `fps=1/${intervalSeconds}`, '-q:v', '3', '-qmin', '2', '-qmax', '4', pattern],
+        { maxBuffer: 1024 * 1024 * 20, timeout: params.timeoutMs, windowsHide: true },
+      );
+    } catch (error: any) {
+      if (error?.code === 'ENOENT') throw new Error(`FFmpeg binary not found`);
+      throw error;
+    }
+
+    const frameFiles = (await fs.readdir(framesDir))
+      .filter((n) => n.toLowerCase().endsWith('.jpg'))
+      .sort((a, b) => a.localeCompare(b));
+
+    if (frameFiles.length === 0) {
+      await (this.prisma as any).course_lesson_video_frame.deleteMany({ where: { course_lesson_id: params.lessonId } });
+      return [];
+    }
+
+    const uploads: LessonFrameResult[] = [];
+    for (let i = 0; i < frameFiles.length; i++) {
+      const fileName = frameFiles[i];
+      if (!fileName) continue;
+      const framePath = join(framesDir, fileName);
+      const stats = await fs.stat(framePath);
+      const uploaded = await this.fileService.uploadFromPath('lms/lessons/frames', framePath, {
+        originalname: fileName,
+        mimetype: 'image/jpeg',
+      });
+      uploads.push({ fileId: uploaded.id, timeSeconds: i * intervalSeconds, outputBytes: stats.size });
+    }
+
+    await (this.prisma as any).course_lesson_video_frame.deleteMany({ where: { course_lesson_id: params.lessonId } });
+    await (this.prisma as any).course_lesson_video_frame.createMany({
+      data: uploads.map((item) => ({
+        course_lesson_id: params.lessonId,
+        file_id: item.fileId,
+        time_seconds: item.timeSeconds,
+      })),
+    });
+
+    return uploads;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Audio extraction (same logic as CourseVideoConversionService)
+  // ---------------------------------------------------------------------------
+
+  private async extractAndUploadLessonAudio(params: {
+    courseId: number;
+    lessonId: number;
+    localInputPath: string;
+    tempDir: string;
+  }): Promise<number | null> {
+    const ffmpegCmd = this.getFfmpegCommand();
+    const mp3Path = join(params.tempDir, `lesson_${params.lessonId}_audio.mp3`);
+
+    try {
+      await execFileAsync(
+        ffmpegCmd,
+        ['-y', '-i', params.localInputPath, '-vn', '-ar', '16000', '-ac', '1', '-c:a', 'libmp3lame', '-b:a', '32k', mp3Path],
+        { maxBuffer: 1024 * 1024 * 20, windowsHide: true },
+      );
+    } catch {
+      return null;
+    }
+
+    try {
+      const course = await (this.prisma as any).course.findUnique({
+        where: { id: params.courseId },
+        select: { locale_id: true },
+      });
+
+      const uploaded = await this.fileService.uploadFromPath('lms/lessons/audio', mp3Path, {
+        originalname: basename(mp3Path),
+        mimetype: 'audio/mp3',
+      });
+
+      const defaultLocale = await (this.prisma as any).locale.findFirst({
+        where: { OR: [{ code: 'pt-BR' }, { code: 'pt' }] },
+        select: { id: true },
+        orderBy: { id: 'asc' },
+      });
+
+      const resolvedLocaleId = course?.locale_id ?? defaultLocale?.id ?? null;
+
+      const existing = await (this.prisma as any).course_lesson_file.findFirst({
+        where: { course_lesson_id: params.lessonId, type: 'lesson_audio' },
+        select: { id: true },
+      });
+
+      if (existing) {
+        await (this.prisma as any).course_lesson_file.update({
+          where: { id: existing.id },
+          data: { file_id: uploaded.id, locale_id: resolvedLocaleId, title: 'Audio Original.mp3', type: 'lesson_audio', is_public: false },
+        });
+      } else {
+        await (this.prisma as any).course_lesson_file.create({
+          data: {
+            course_lesson_id: params.lessonId,
+            file_id: uploaded.id,
+            title: 'Audio Original.mp3',
+            type: 'lesson_audio',
+            is_public: false,
+            locale_id: resolvedLocaleId,
+          },
+        });
+      }
+
+      return uploaded.id;
+    } catch {
+      return null;
+    } finally {
+      await fs.rm(mp3Path, { force: true }).catch(() => undefined);
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Shared helpers
+  // ---------------------------------------------------------------------------
+
+  private async upsertLessonFile(params: {
+    lessonId: number;
+    type: string;
+    fileId: number;
+    title: string;
+    public: boolean;
+    overwrite: boolean;
+  }) {
+    if (params.overwrite) {
+      await (this.prisma as any).course_lesson_file.deleteMany({
+        where: { course_lesson_id: params.lessonId, type: params.type },
+      });
+    }
+
+    return (this.prisma as any).course_lesson_file.create({
+      data: {
+        course_lesson_id: params.lessonId,
+        file_id: params.fileId,
+        title: params.title,
+        type: params.type,
+        is_public: params.public,
+      },
+    });
+  }
+
+  private async createProgressEvent(
+    queueJobId: number,
+    message: string,
+    metadata?: Record<string, unknown>,
+    notificationContext?: NotificationContext,
+  ) {
+    try {
+      await (this.prisma as any).queue_job_event.create({
+        data: { queue_job_id: queueJobId, event_type: 'started', message, ...(metadata ? { metadata } : {}) },
+      });
+    } catch (error) {
+      this.logger.warn(`Failed to persist progress event: ${error instanceof Error ? error.message : 'unknown'}`);
+    }
+
+    if (notificationContext) {
+      const progress = this.resolveNotificationProgress(metadata);
+      await this.updateAsyncNotification(notificationContext, progress, message);
+    }
+  }
+
+  private resolveNotificationProgress(metadata?: Record<string, unknown>): number {
+    const phase = String(metadata?.phase ?? '');
+    if (phase === 'download_original') return 5;
+    if (phase === 'probe_duration') return 12;
+    if (phase === 'hls_encode') return 20;
+    if (phase === 'hls_upload') return 65;
+    if (phase === 'extract_frames') return 72;
+    if (phase === 'extract_frames_done') return 78;
+    if (phase === 'extract_audio') return 83;
+    if (phase === 'queue_transcription') return 90;
+    if (phase === 'queue_transcription_done') return 92;
+    if (phase === 'queue_transcription_skipped') return 100;
+    return 15;
+  }
+
+  private async updateAsyncNotification(context: NotificationContext, progress: number, body: string, success?: boolean) {
+    try {
+      await this.notificationService.updateProgress(context.userId, context.notificationId, {
+        progress,
+        body,
+        ...(success != null ? { success } : {}),
+      });
+    } catch (error) {
+      this.logger.warn(`Failed to update notification ${context.notificationId}: ${error instanceof Error ? error.message : 'unknown'}`);
+    }
+  }
+
+  private parseContent(content: string | null | undefined): Record<string, unknown> | null {
+    if (!content) return null;
+    try { return JSON.parse(content); } catch { return null; }
+  }
+
+  private isVideoFile(mimetype: string, filename?: string): boolean {
+    if (mimetype.startsWith('video/')) return true;
+    const ext = (filename ?? '').split('.').pop()?.toLowerCase() ?? '';
+    return ['mp4', 'm4v', 'mov', 'mkv', 'webm', 'avi', 'wmv', 'flv', 'ogv', 'm2ts', 'ts'].includes(ext);
+  }
+
+  private resolveFrameIntervalSeconds(raw: unknown): number {
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 1 ? Math.floor(n) : 10;
+  }
+
+  private getPositiveIntegerEnv(name: string): number | undefined {
+    const raw = process.env[name];
+    if (!raw) return undefined;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+  }
+
+  private getFfmpegCommand(): string {
+    const fromEnv = process.env.FFMPEG_PATH?.trim();
+    if (fromEnv) return fromEnv;
+    if (process.platform === 'win32') {
+      const found = this.findWindowsBinary('ffmpeg');
+      if (found) return found;
+    }
+    return 'ffmpeg';
+  }
+
+  private getFfprobeCommand(): string {
+    const fromEnv = process.env.FFPROBE_PATH?.trim();
+    if (fromEnv) return fromEnv;
+    const ffmpegEnv = process.env.FFMPEG_PATH?.trim();
+    if (ffmpegEnv) {
+      const candidate = ffmpegEnv.replace(/ffmpeg(\.exe)?$/i, (_, ext) => `ffprobe${ext ?? ''}`);
+      if (existsSync(candidate)) return candidate;
+    }
+    if (process.platform === 'win32') {
+      const found = this.findWindowsBinary('ffprobe');
+      if (found) return found;
+    }
+    return 'ffprobe';
+  }
+
+  private findWindowsBinary(name: 'ffmpeg' | 'ffprobe'): string | null {
+    const localAppData = process.env.LOCALAPPDATA;
+    if (!localAppData) return null;
+    const packagesRoot = join(localAppData, 'Microsoft', 'WinGet', 'Packages');
+    try {
+      const packageDirs = readdirSync(packagesRoot, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && e.name.startsWith('Gyan.FFmpeg'))
+        .map((e) => join(packagesRoot, e.name))
+        .sort((a, b) => b.localeCompare(a));
+
+      for (const dir of packageDirs) {
+        const direct = join(dir, 'bin', `${name}.exe`);
+        if (existsSync(direct)) return direct;
+        try {
+          const versionDirs = readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && e.name.toLowerCase().startsWith('ffmpeg-'))
+            .map((e) => join(dir, e.name))
+            .sort((a, b) => b.localeCompare(a));
+          for (const vd of versionDirs) {
+            const candidate = join(vd, 'bin', `${name}.exe`);
+            if (existsSync(candidate)) return candidate;
+          }
+        } catch { /* skip */ }
+      }
+    } catch { /* skip */ }
+    return null;
+  }
+}