@hed-hog/lms 0.0.353 → 0.0.355

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

@@ -1,5 +1,5 @@
 import { PrismaService } from '@hed-hog/api-prisma';
-import { FileService } from '@hed-hog/core';
+import { FileService, NotificationService, SettingService } from '@hed-hog/core';
 import { IJobHandler, QueueHandlerRegistry, QueueJobService } from '@hed-hog/queue';
 import {
     BadRequestException,
@@ -11,7 +11,7 @@ import {
     forwardRef,
 } from '@nestjs/common';
 import { execFile } from 'child_process';
-import { promises as fs } from 'fs';
+import { existsSync, promises as fs, readdirSync } from 'fs';
 import { tmpdir } from 'os';
 import { basename, join } from 'path';
 import { promisify } from 'util';
@@ -24,17 +24,110 @@ type VideoProfilePayload = {
   ffmpeg_params: string;
 };
 
+type LessonFrameResult = {
+  fileId: number;
+  timeSeconds: number;
+  outputBytes: number;
+};
+
 const execFileAsync = promisify(execFile);
 
+type NotificationContext = {
+  userId: number;
+  notificationId: number;
+};
+
 @Injectable()
 export class CourseVideoConversionService implements OnModuleInit, IJobHandler {
   private readonly logger = new Logger(CourseVideoConversionService.name);
 
+  private async createProgressEvent(
+    queueJobId: number,
+    message: string,
+    metadata?: Record<string, unknown>,
+    notificationContext?: NotificationContext,
+  ): Promise<void> {
+    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(
+        `Queue job ${queueJobId}: failed to persist progress event "${message}": ${error instanceof Error ? error.message : 'unknown error'}`,
+      );
+    }
+
+    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 10;
+    if (phase === 'convert_profile') {
+      const profileIndex = Number(metadata?.profileIndex ?? 0);
+      const profileCount = Number(metadata?.profileCount ?? 0);
+      if (profileIndex > 0 && profileCount > 0) {
+        const ratio = Math.min(1, Math.max(0, profileIndex / profileCount));
+        return 10 + Math.round(ratio * 45);
+      }
+      return 40;
+    }
+    if (phase === 'extract_frames') return 65;
+    if (phase === 'extract_frames_done') return 72;
+    if (phase === 'extract_audio') return 80;
+    if (phase === 'queue_transcription') return 88;
+    if (phase === 'queue_transcription_done') return 90;
+    if (phase === 'queue_transcription_skipped') return 100;
+
+    return 15;
+  }
+
+  private async updateAsyncNotification(
+    context: NotificationContext,
+    progress: number,
+    body: string,
+    success?: boolean,
+  ): Promise<void> {
+    try {
+      await this.notificationService.updateProgress(
+        context.userId,
+        context.notificationId,
+        {
+          progress,
+          body,
+          ...(success != null ? { success } : {}),
+        },
+      );
+    } catch (error) {
+      this.logger.warn(
+        `Failed to update async notification ${context.notificationId} for user ${context.userId}: ${error instanceof Error ? error.message : 'unknown error'}`,
+      );
+    }
+  }
+
   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))
@@ -47,11 +140,21 @@ export class CourseVideoConversionService implements OnModuleInit, IJobHandler {
   }
 
   async enqueueConversion(params: {
+    userId: number;
     courseId: number;
     sessionId: number;
     lessonId: number;
     originalFileId: number;
   }) {
+    const settings = await this.settingService.getSettingValues(
+      'lms-video-conversion-enabled',
+    );
+    const isVideoConversionEnabled = settings['lms-video-conversion-enabled'] !== false;
+
+    if (!isVideoConversionEnabled) {
+      throw new BadRequestException('Video conversion queue is disabled by settings');
+    }
+
     const lesson = await (this.prisma as any).course_lesson.findFirst({
       where: {
         id: params.lessonId,
@@ -102,6 +205,23 @@ export class CourseVideoConversionService implements OnModuleInit, IJobHandler {
       overwrite: true,
     });
 
+    const asyncNotification = await this.notificationService.create({
+      user_id: params.userId,
+      title: 'Conversão e transcrição de vídeo em andamento',
+      body: 'Preparando pipeline de processamento 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-conversion',
+        courseId: params.courseId,
+        lessonId: params.lessonId,
+      },
+    });
+
     const job = await this.queueJob.enqueue({
       type: LMS_VIDEO_CONVERSION_JOB,
       queueName: LMS_VIDEO_CONVERSION_JOB,
@@ -112,6 +232,8 @@ export class CourseVideoConversionService implements OnModuleInit, IJobHandler {
         originalFileId: params.originalFileId,
         profiles,
         overwrite: true,
+        notificationId: asyncNotification.id,
+        notificationUserId: params.userId,
       },
       sourceModule: 'lms',
       sourceEntity: 'course_lesson',
@@ -145,8 +267,26 @@ export class CourseVideoConversionService implements OnModuleInit, IJobHandler {
         originalFileId?: number;
         profiles?: VideoProfilePayload[];
         overwrite?: boolean;
+        notificationId?: number;
+        notificationUserId?: number;
       };
 
+    const notificationContext: NotificationContext | undefined =
+      Number.isInteger(Number((job.payload as any)?.notificationId)) &&
+      Number.isInteger(Number((job.payload as any)?.notificationUserId))
+        ? {
+            notificationId: Number((job.payload as any).notificationId),
+            userId: Number((job.payload as any).notificationUserId),
+          }
+        : undefined;
+
+    const emitProgress = async (
+      message: string,
+      metadata?: Record<string, unknown>,
+    ) => {
+      await this.createProgressEvent(job.id, message, metadata, notificationContext);
+    };
+
     if (!courseId || !sessionId || !lessonId || !originalFileId || !profiles?.length) {
       throw new Error('Invalid LMS video conversion payload');
     }
@@ -162,6 +302,16 @@ export class CourseVideoConversionService implements OnModuleInit, IJobHandler {
     const maxInputBytes = this.getPositiveIntegerEnv('LMS_VIDEO_MAX_INPUT_BYTES');
     const ffmpegTimeoutMs =
       this.getPositiveIntegerEnv('LMS_VIDEO_FFMPEG_TIMEOUT_MS') ?? 1000 * 60 * 60;
+    const intervalSettings = await this.settingService.getSettingValues([
+      'lms-video-frame-capture-interval-seconds',
+      'lms-image-extraction-enabled',
+      'lms-audio-transcription-enabled',
+    ]);
+    const frameIntervalSeconds = this.resolveFrameIntervalSeconds(
+      intervalSettings['lms-video-frame-capture-interval-seconds'],
+    );
+    const imageExtractionEnabled = intervalSettings['lms-image-extraction-enabled'] !== false;
+    const transcriptionEnabled = intervalSettings['lms-audio-transcription-enabled'] !== false;
 
     const workDir = await fs.mkdtemp(join(tmpdir(), `lms-video-${job.id}-`));
     const inputPath = join(workDir, `original-${originalFileId}.mp4`);
@@ -169,6 +319,13 @@ export class CourseVideoConversionService implements OnModuleInit, IJobHandler {
     this.logger.log(
       `Queue job ${job.id}: starting LMS video conversion (lesson=${lessonId}, profiles=${profilesToProcess.length})`,
     );
+    await emitProgress('Baixando vídeo original...', {
+      phase: 'download_original',
+      lessonId,
+    });
+    this.logger.debug(
+      `Queue job ${job.id}: payload resolved (course=${courseId}, session=${sessionId}, lesson=${lessonId}, originalFileId=${originalFileId}, overwrite=${overwrite !== false}, ffmpegTimeoutMs=${ffmpegTimeoutMs}, frameIntervalSeconds=${frameIntervalSeconds}, profiles=[${profilesToProcess.map((profile) => profile.id).join(', ')}])`,
+    );
 
     const downloadedOriginal = await this.fileService.downloadToPath(
       originalFileId,
@@ -179,6 +336,26 @@ export class CourseVideoConversionService implements OnModuleInit, IJobHandler {
     this.logger.log(
       `Queue job ${job.id}: original file downloaded (lesson=${lessonId}, size=${downloadedOriginal.size})`,
     );
+    await emitProgress('Vídeo original baixado. Lendo duração...', {
+      phase: 'probe_duration',
+      lessonId,
+    });
+
+    let probedDuration: number | null = null;
+    try {
+      probedDuration = await this.probeDurationSeconds(inputPath, ffmpegTimeoutMs);
+      if (probedDuration !== null && probedDuration > 0) {
+        await (this.prisma as any).course_lesson.update({
+          where: { id: lessonId },
+          data: { duration_seconds: probedDuration },
+        });
+        this.logger.log(
+          `Queue job ${job.id}: probed video duration=${probedDuration}s, updated lesson ${lessonId}`,
+        );
+      }
+    } catch (err: any) {
+      this.logger.warn(`Queue job ${job.id}: failed to probe duration for lesson ${lessonId}: ${err?.message ?? err}`);
+    }
 
     const jobStartedAt = Date.now();
     const results: Array<{
@@ -191,6 +368,7 @@ export class CourseVideoConversionService implements OnModuleInit, IJobHandler {
       uploadMBps: number;
       totalMs: number;
     }> = [];
+    let frameResults: LessonFrameResult[] = [];
 
     try {
       for (const profile of profilesToProcess) {
@@ -202,6 +380,20 @@ export class CourseVideoConversionService implements OnModuleInit, IJobHandler {
         this.logger.log(
           `Queue job ${job.id}: converting profile ${profile.id} for lesson ${lessonId}`,
         );
+        await emitProgress(
+          `Convertendo vídeo para o perfil ${profile.name || profile.id}...`,
+          {
+            phase: 'convert_profile',
+            lessonId,
+            profileId: profile.id,
+            profileName: profile.name,
+            profileIndex: results.length + 1,
+            profileCount: profilesToProcess.length,
+          },
+        );
+        this.logger.debug(
+          `Queue job ${job.id}: profile ${profile.id} ffmpeg params="${profile.ffmpeg_params}" outputPath=${outputPath}`,
+        );
 
         const conversionStartedAt = Date.now();
         await this.convert(inputPath, outputPath, profile.ffmpeg_params, ffmpegTimeoutMs);
@@ -243,6 +435,259 @@ export class CourseVideoConversionService implements OnModuleInit, IJobHandler {
           `Queue job ${job.id}: profile ${profile.id} done for lesson ${lessonId} (fileId=${uploaded.id}, outputBytes=${outputStats.size}, conversionMs=${conversionMs}, conversionMBps=${conversionMBps.toFixed(2)}, uploadMs=${uploadMs}, uploadMBps=${uploadMBps.toFixed(2)}, totalMs=${totalMs})`,
         );
       }
+
+      if (imageExtractionEnabled) {
+        await emitProgress('Extraindo imagens do vídeo...', {
+          phase: 'extract_frames',
+          lessonId,
+        });
+        this.logger.debug(
+          `Queue job ${job.id}: starting frame extraction for lesson ${lessonId}`,
+        );
+        frameResults = await this.extractAndUploadLessonFrames({
+          jobId: job.id,
+          lessonId,
+          inputPath,
+          workDir,
+          intervalSeconds: frameIntervalSeconds,
+          timeoutMs: ffmpegTimeoutMs,
+        });
+        this.logger.debug(
+          `Queue job ${job.id}: frame extraction finished for lesson ${lessonId} (frames=${frameResults.length})`,
+        );
+        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(
+          `Queue job ${job.id}: skipping frame extraction for lesson ${lessonId} (lms-image-extraction-enabled=false)`,
+        );
+      }
+
+      if (transcriptionEnabled) {
+      await emitProgress('Extraindo áudio do vídeo...', {
+        phase: 'extract_audio',
+        lessonId,
+      });
+      this.logger.debug(
+        `Queue job ${job.id}: starting audio extraction for lesson ${lessonId}`,
+      );
+      const audioFileId = await this.extractAndUploadLessonAudio({
+        courseId,
+        lessonId,
+        localInputPath: inputPath,
+        tempDir: workDir,
+      });
+      this.logger.debug(
+        `Queue job ${job.id}: audio extraction finished for lesson ${lessonId} (audioFileId=${audioFileId ?? 'null'})`,
+      );
+
+      if (audioFileId) {
+        await emitProgress('Áudio extraído. Agendando transcrição...', {
+          phase: 'queue_transcription',
+          lessonId,
+          audioFileId,
+        });
+        this.logger.debug(
+          `Queue job ${job.id}: enqueueing transcription job for lesson ${lessonId} with audioFileId=${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 em IA agendada no job #${transcriptionJob.id}.`,
+          {
+            phase: 'queue_transcription_done',
+            lessonId,
+            audioFileId,
+            transcriptionJobId: transcriptionJob.id,
+          },
+        );
+        return {
+          lessonId,
+          probedDurationSeconds: probedDuration ?? null,
+          converted: results.length,
+          results,
+          extractedFrames: frameResults.length,
+          frames: frameResults,
+          transcriptionJobId: transcriptionJob.id,
+          metrics: {
+            totalMs: Date.now() - jobStartedAt,
+            totalOutputBytes: results.reduce((acc, item) => acc + item.outputBytes, 0),
+            averageProfileMs:
+              results.length > 0
+                ? Math.round(results.reduce((acc, item) => acc + item.totalMs, 0) / results.length)
+                : 0,
+            averageConversionMBps:
+              results.length > 0
+                ? Number(
+                    (
+                      results.reduce((acc, item) => acc + item.conversionMBps, 0) / results.length
+                    ).toFixed(2),
+                  )
+                : 0,
+            averageUploadMBps:
+              results.length > 0
+                ? Number(
+                    (results.reduce((acc, item) => acc + item.uploadMBps, 0) / results.length).toFixed(2),
+                  )
+                : 0,
+          },
+        };
+      } else {
+        let transcriptionSkipReason = 'audio extraction returned no file id';
+        try {
+          const existingAudio = await (this.prisma as any).course_lesson_file.findFirst({
+            where: {
+              course_lesson_id: lessonId,
+              type: 'lesson_audio',
+              file_id: { not: null },
+            },
+            orderBy: { id: 'desc' },
+            select: { file_id: true },
+          });
+
+          const fallbackAudioFileId = Number(existingAudio?.file_id ?? 0);
+          if (fallbackAudioFileId > 0) {
+            transcriptionSkipReason =
+              'audio extraction returned no file id, using existing lesson_audio fallback';
+            this.logger.warn(
+              `Queue job ${job.id}: audio extraction returned null for lesson ${lessonId}; enqueueing transcription with existing lesson_audio fileId=${fallbackAudioFileId}`,
+            );
+
+            await emitProgress(
+              'Áudio reutilizado de execução anterior. Agendando transcrição...',
+              {
+                phase: 'queue_transcription',
+                lessonId,
+                audioFileId: fallbackAudioFileId,
+                fallback: true,
+              },
+            );
+
+            const transcriptionJob = await this.queueJob.enqueue({
+              type: 'lms.audio.transcribe',
+              queueName: 'lms.audio.transcribe',
+              payload: {
+                courseId,
+                sessionId,
+                lessonId,
+                audioFileId: fallbackAudioFileId,
+                parentJobId: job.id,
+                notificationId: notificationContext?.notificationId,
+                notificationUserId: notificationContext?.userId,
+              },
+              maxAttempts: 3,
+            });
+
+            await emitProgress(
+              `Transcrição em IA agendada no job #${transcriptionJob.id}.`,
+              {
+                phase: 'queue_transcription_done',
+                lessonId,
+                audioFileId: fallbackAudioFileId,
+                transcriptionJobId: transcriptionJob.id,
+                fallback: true,
+              },
+            );
+
+            return {
+              lessonId,
+              probedDurationSeconds: probedDuration ?? null,
+              converted: results.length,
+              results,
+              extractedFrames: frameResults.length,
+              frames: frameResults,
+              transcriptionJobId: transcriptionJob.id,
+              metrics: {
+                totalMs: Date.now() - jobStartedAt,
+                totalOutputBytes: results.reduce((acc, item) => acc + item.outputBytes, 0),
+                averageProfileMs:
+                  results.length > 0
+                    ? Math.round(results.reduce((acc, item) => acc + item.totalMs, 0) / results.length)
+                    : 0,
+                averageConversionMBps:
+                  results.length > 0
+                    ? Number(
+                        (
+                          results.reduce((acc, item) => acc + item.conversionMBps, 0) / results.length
+                        ).toFixed(2),
+                      )
+                    : 0,
+                averageUploadMBps:
+                  results.length > 0
+                    ? Number(
+                        (results.reduce((acc, item) => acc + item.uploadMBps, 0) / results.length).toFixed(2),
+                      )
+                    : 0,
+              },
+            };
+          }
+        } catch (fallbackError) {
+          transcriptionSkipReason = `fallback lookup failed: ${fallbackError instanceof Error ? fallbackError.message : 'unknown error'}`;
+          this.logger.warn(
+            `Queue job ${job.id}: fallback lookup for lesson_audio failed on lesson ${lessonId}: ${fallbackError instanceof Error ? fallbackError.message : 'unknown error'}`,
+          );
+        }
+
+        this.logger.debug(
+          `Queue job ${job.id}: skipping transcription enqueue for lesson ${lessonId} because no audio file was produced (${transcriptionSkipReason})`,
+        );
+        await emitProgress(
+          'Áudio não disponível. Encerrando pipeline sem transcrição.',
+          {
+            phase: 'queue_transcription_skipped',
+            lessonId,
+            reason: transcriptionSkipReason,
+          },
+        );
+
+        if (notificationContext) {
+          await this.updateAsyncNotification(
+            notificationContext,
+            100,
+            'Pipeline concluído sem transcrição: áudio indisponível para processamento.',
+            true,
+          );
+        }
+      }
+      } else {
+        this.logger.debug(
+          `Queue job ${job.id}: skipping audio extraction and transcription for lesson ${lessonId} (lms-audio-transcription-enabled=false)`,
+        );
+      }
+    } catch (error) {
+      if (notificationContext) {
+        const message =
+          error instanceof Error && error.message
+            ? error.message
+            : 'Falha ao processar conversão de vídeo.';
+        await this.updateAsyncNotification(
+          notificationContext,
+          100,
+          `Falha no pipeline de vídeo: ${message}`,
+          false,
+        );
+      }
+      throw error;
     } finally {
       await fs.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
       this.logger.log(`Queue job ${job.id}: cleaned temporary folder ${workDir}`);
@@ -255,10 +700,23 @@ export class CourseVideoConversionService implements OnModuleInit, IJobHandler {
       `Queue job ${job.id}: LMS conversion finished (lesson=${lessonId}, profiles=${results.length}, totalMs=${totalMs}, totalOutputBytes=${totalOutputBytes})`,
     );
 
+    if (notificationContext) {
+      await this.updateAsyncNotification(
+        notificationContext,
+        100,
+        'Conversão e transcrição concluídas com sucesso.',
+        true,
+      );
+    }
+
     return {
       lessonId,
+      probedDurationSeconds: probedDuration ?? null,
       converted: results.length,
       results,
+      extractedFrames: frameResults.length,
+      frames: frameResults,
+      transcriptionJobId: null,
       metrics: {
         totalMs,
         totalOutputBytes,
@@ -284,6 +742,301 @@ export class CourseVideoConversionService implements OnModuleInit, IJobHandler {
     };
   }
 
+  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');
+
+    this.logger.log(
+      `Queue job ${params.jobId}: extracting lesson frames every ${intervalSeconds}s (lesson=${params.lessonId})`,
+    );
+    this.logger.debug(
+      `Queue job ${params.jobId}: frame extraction input=${params.inputPath} outputPattern=${pattern} timeoutMs=${params.timeoutMs}`,
+    );
+
+    await this.extractFramesFromVideo(
+      params.inputPath,
+      pattern,
+      intervalSeconds,
+      params.timeoutMs,
+    );
+
+    const frameFiles = (await fs.readdir(framesDir))
+      .filter((name) => name.toLowerCase().endsWith('.jpg'))
+      .sort((a, b) => a.localeCompare(b));
+    this.logger.debug(
+      `Queue job ${params.jobId}: frame extraction produced ${frameFiles.length} file(s) in ${framesDir}`,
+    );
+
+    if (frameFiles.length === 0) {
+      this.logger.warn(
+        `Queue job ${params.jobId}: no frames extracted for lesson ${params.lessonId}`,
+      );
+      await (this.prisma as any).course_lesson_video_frame.deleteMany({
+        where: { course_lesson_id: params.lessonId },
+      });
+      return [];
+    }
+
+    const uploads: LessonFrameResult[] = [];
+    for (let index = 0; index < frameFiles.length; index += 1) {
+      const fileName = frameFiles[index];
+      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: index * intervalSeconds,
+        outputBytes: stats.size,
+      });
+      this.logger.debug(
+        `Queue job ${params.jobId}: uploaded frame ${fileName} -> fileId=${uploaded.id}, timeSeconds=${index * 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,
+      })),
+    });
+
+    this.logger.log(
+      `Queue job ${params.jobId}: extracted and uploaded ${uploads.length} lesson frames (lesson=${params.lessonId})`,
+    );
+
+    return uploads;
+  }
+
+  private async extractAndUploadLessonAudio(params: {
+    courseId: number;
+    lessonId: number;
+    localInputPath: string;
+    tempDir: string;
+  }): Promise<number | null> {
+    const ffmpegCommand = this.getFfmpegCommand();
+    const mp3Path = join(params.tempDir, `lesson_${params.lessonId}_audio.mp3`);
+    const mp3LowBitratePath = join(
+      params.tempDir,
+      `lesson_${params.lessonId}_audio.low.mp3`,
+    );
+
+    let outputPath = mp3Path;
+    const mimetype = 'audio/mp3';
+
+    this.logger.debug(
+      `Audio extraction: lesson=${params.lessonId}, input=${params.localInputPath}, preferredOutput=${mp3Path}`,
+    );
+
+    try {
+      await execFileAsync(
+        ffmpegCommand,
+        [
+          '-y',
+          '-i',
+          params.localInputPath,
+          '-vn',
+          '-ar',
+          '16000',
+          '-ac',
+          '1',
+          '-c:a',
+          'libmp3lame',
+          '-b:a',
+          '32k',
+          mp3Path,
+        ],
+        {
+          maxBuffer: 1024 * 1024 * 20,
+          windowsHide: true,
+        },
+      );
+    } catch (error) {
+      this.logger.warn(
+        `Audio extraction failed for lesson ${params.lessonId}: ${error instanceof Error ? error.message : 'unknown error'}`,
+      );
+      return null;
+    }
+
+    let uploadedAudioId: number | null = null;
+    try {
+      const course = await (this.prisma as any).course.findUnique({
+        where: { id: params.courseId },
+        select: { locale_id: true },
+      });
+
+      let uploaded;
+      try {
+        uploaded = await this.fileService.uploadFromPath('lms/lessons/audio', outputPath, {
+          originalname: basename(outputPath),
+          mimetype,
+        });
+      } catch (uploadError) {
+        // Retry with an even smaller bitrate when storage max size is too strict.
+        this.logger.warn(
+          `Audio upload first attempt failed for lesson ${params.lessonId}, retrying with lower bitrate: ${uploadError instanceof Error ? uploadError.message : 'unknown error'}`,
+        );
+
+        outputPath = mp3LowBitratePath;
+        await execFileAsync(
+          ffmpegCommand,
+          [
+            '-y',
+            '-i',
+            params.localInputPath,
+            '-vn',
+            '-ar',
+            '16000',
+            '-ac',
+            '1',
+            '-c:a',
+            'libmp3lame',
+            '-b:a',
+            '16k',
+            mp3LowBitratePath,
+          ],
+          {
+            maxBuffer: 1024 * 1024 * 20,
+            windowsHide: true,
+          },
+        );
+
+        uploaded = await this.fileService.uploadFromPath('lms/lessons/audio', outputPath, {
+          originalname: basename(outputPath),
+          mimetype,
+        });
+      }
+      uploadedAudioId = uploaded.id;
+      this.logger.debug(
+        `Audio extraction: lesson=${params.lessonId} uploaded audio fileId=${uploaded.id}, mimetype=${mimetype}, outputPath=${outputPath}`,
+      );
+
+      const existingAudio = await (this.prisma as any).course_lesson_file.findFirst({
+        where: {
+          course_lesson_id: params.lessonId,
+          type: 'lesson_audio',
+        },
+        select: { id: true, locale_id: true },
+      });
+
+      const defaultLocale = await (this.prisma as any).locale.findFirst({
+        where: {
+          OR: [{ code: 'pt-BR' }, { code: 'pt' }],
+        },
+        select: { id: true },
+        orderBy: { id: 'asc' },
+      });
+      const resolvedLocaleId =
+        existingAudio?.locale_id ?? course?.locale_id ?? defaultLocale?.id ?? null;
+      const audioTitle = 'Audio Original.mp3';
+
+      if (existingAudio) {
+        await (this.prisma as any).course_lesson_file.update({
+          where: { id: existingAudio.id },
+          data: {
+            file_id: uploaded.id,
+            locale_id: resolvedLocaleId,
+            title: audioTitle,
+            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: audioTitle,
+            type: 'lesson_audio',
+            is_public: false,
+            locale_id: resolvedLocaleId,
+          },
+        });
+      }
+
+      return uploaded.id;
+    } catch (error) {
+      if (uploadedAudioId) {
+        this.logger.warn(
+          `Audio metadata upsert failed for lesson ${params.lessonId}, but audio upload succeeded (fileId=${uploadedAudioId}): ${error instanceof Error ? error.message : 'unknown error'}`,
+        );
+        return uploadedAudioId;
+      }
+
+      this.logger.warn(
+        `Audio upload failed for lesson ${params.lessonId}: ${error instanceof Error ? error.message : 'unknown error'}`,
+      );
+      return null;
+    } finally {
+      this.logger.debug(
+        `Audio extraction: lesson=${params.lessonId} cleaning temporary audio files (${mp3Path}, ${mp3LowBitratePath})`,
+      );
+      await fs.rm(mp3Path, { force: true }).catch(() => undefined);
+      await fs.rm(mp3LowBitratePath, { force: true }).catch(() => undefined);
+    }
+  }
+
+  private async extractFramesFromVideo(
+    inputPath: string,
+    outputPattern: string,
+    intervalSeconds: number,
+    timeoutMs: number,
+  ) {
+    const ffmpegCommand = this.getFfmpegCommand();
+    const args = [
+      '-y',
+      '-i',
+      inputPath,
+      '-vf',
+      `fps=1/${intervalSeconds}`,
+      '-q:v',
+      '3',
+      '-qmin',
+      '2',
+      '-qmax',
+      '4',
+      outputPattern,
+    ];
+
+    try {
+      await execFileAsync(ffmpegCommand, args, {
+        maxBuffer: 1024 * 1024 * 20,
+        timeout: timeoutMs,
+        windowsHide: true,
+      });
+    } catch (error: any) {
+      if (error?.code === 'ENOENT') {
+        throw new Error(
+          `FFmpeg binary not found. Configure FFMPEG_PATH or ensure "${ffmpegCommand}" is available in PATH`,
+        );
+      }
+      if (error?.killed && error?.signal === 'SIGTERM') {
+        throw new Error(`FFmpeg frame extraction timed out after ${timeoutMs}ms`);
+      }
+      throw error;
+    }
+  }
+
   private async getCourseProfiles(courseId: number): Promise<VideoProfilePayload[]> {
     const rows = await (this.prisma as any).course_video_resolution_profile.findMany({
       where: { course_id: courseId },
@@ -309,11 +1062,13 @@ export class CourseVideoConversionService implements OnModuleInit, IJobHandler {
     public: boolean;
     overwrite: boolean;
   }) {
+    const normalizedType = this.normalizeLessonFileType(params.type);
+
     if (params.overwrite) {
       await (this.prisma as any).course_lesson_file.deleteMany({
         where: {
           course_lesson_id: params.lessonId,
-          tipo: params.type,
+          type: normalizedType,
         },
       });
     }
@@ -323,26 +1078,52 @@ export class CourseVideoConversionService implements OnModuleInit, IJobHandler {
         course_lesson_id: params.lessonId,
         file_id: params.fileId,
         title: params.title,
-        tipo: params.type,
-        publico: params.public,
+        type: normalizedType,
+        is_public: params.public,
       },
     });
   }
 
+  private normalizeLessonFileType(value?: string | null) {
+    if (value === 'video_original') {
+      return 'video_original';
+    }
+
+    if (value?.startsWith('video_profile:')) {
+      return value;
+    }
+
+    if (value === 'lesson_audio') {
+      return 'lesson_audio';
+    }
+
+    if (value === 'student_download' || value === 'file' || value === 'download') {
+      return 'student_download';
+    }
+
+    return 'supplementary_material';
+  }
+
   private async convert(
     inputPath: string,
     outputPath: string,
     params: string,
     timeoutMs: number,
   ) {
+    const ffmpegCommand = this.getFfmpegCommand();
     const args = ['-y', '-i', inputPath, ...this.splitFfmpegParams(params), outputPath];
     try {
-      await execFileAsync('ffmpeg', args, {
+      await execFileAsync(ffmpegCommand, args, {
         maxBuffer: 1024 * 1024 * 20,
         timeout: timeoutMs,
         windowsHide: true,
       });
     } catch (error: any) {
+      if (error?.code === 'ENOENT') {
+        throw new Error(
+          `FFmpeg binary not found. Configure FFMPEG_PATH or ensure "${ffmpegCommand}" is available in PATH`,
+        );
+      }
       if (error?.killed && error?.signal === 'SIGTERM') {
         throw new Error(`FFmpeg timed out after ${timeoutMs}ms`);
       }
@@ -350,6 +1131,176 @@ export class CourseVideoConversionService implements OnModuleInit, IJobHandler {
     }
   }
 
+  private getFfmpegCommand(): string {
+    const fromEnv = process.env.FFMPEG_PATH?.trim();
+    if (fromEnv) {
+      return fromEnv;
+    }
+
+    if (process.platform === 'win32') {
+      const fromWinget = this.findWindowsWingetFfmpeg();
+      if (fromWinget) {
+        return fromWinget;
+      }
+    }
+
+    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 fromWinget = this.findWindowsWingetFfprobe();
+      if (fromWinget) {
+        return fromWinget;
+      }
+    }
+
+    return 'ffprobe';
+  }
+
+  private findWindowsWingetFfprobe(): string | null {
+    const localAppData = process.env.LOCALAPPDATA;
+    if (!localAppData) {
+      return null;
+    }
+
+    const wingetPackagesRoot = join(localAppData, 'Microsoft', 'WinGet', 'Packages');
+
+    try {
+      const packageDirs = readdirSync(wingetPackagesRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && entry.name.startsWith('Gyan.FFmpeg'))
+        .map((entry) => join(wingetPackagesRoot, entry.name))
+        .sort((a, b) => b.localeCompare(a));
+
+      for (const packageDir of packageDirs) {
+        const executable = this.findFfprobeExecutableInside(packageDir);
+        if (executable) {
+          return executable;
+        }
+      }
+    } catch {
+      return null;
+    }
+
+    return null;
+  }
+
+  private findFfprobeExecutableInside(baseDir: string): string | null {
+    const directCandidate = join(baseDir, 'bin', 'ffprobe.exe');
+    if (existsSync(directCandidate)) {
+      return directCandidate;
+    }
+
+    try {
+      const versionDirs = readdirSync(baseDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && entry.name.toLowerCase().startsWith('ffmpeg-'))
+        .map((entry) => join(baseDir, entry.name))
+        .sort((a, b) => b.localeCompare(a));
+
+      for (const versionDir of versionDirs) {
+        const candidate = join(versionDir, 'bin', 'ffprobe.exe');
+        if (existsSync(candidate)) {
+          return candidate;
+        }
+      }
+    } catch {
+      return null;
+    }
+
+    return null;
+  }
+
+  private async probeDurationSeconds(inputPath: string, timeoutMs: number): Promise<number | null> {
+    const ffprobeCommand = this.getFfprobeCommand();
+    const args = [
+      '-v', 'error',
+      '-show_entries', 'format=duration',
+      '-of', 'default=noprint_wrappers=1:nokey=1',
+      inputPath,
+    ];
+
+    try {
+      const { stdout } = await execFileAsync(ffprobeCommand, args, {
+        maxBuffer: 1024 * 1024,
+        timeout: Math.min(timeoutMs, 30_000),
+        windowsHide: true,
+      });
+      const parsed = parseFloat(stdout.trim());
+      if (!Number.isFinite(parsed) || parsed <= 0) {
+        return null;
+      }
+      return Math.round(parsed);
+    } catch (error: any) {
+      this.logger.warn(`FFprobe duration extraction failed: ${error?.message ?? error}`);
+      return null;
+    }
+  }
+
+  private findWindowsWingetFfmpeg(): string | null {
+    const localAppData = process.env.LOCALAPPDATA;
+    if (!localAppData) {
+      return null;
+    }
+
+    const wingetPackagesRoot = join(localAppData, 'Microsoft', 'WinGet', 'Packages');
+
+    try {
+      const packageDirs = readdirSync(wingetPackagesRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && entry.name.startsWith('Gyan.FFmpeg'))
+        .map((entry) => join(wingetPackagesRoot, entry.name))
+        .sort((a, b) => b.localeCompare(a));
+
+      for (const packageDir of packageDirs) {
+        const executable = this.findFfmpegExecutableInside(packageDir);
+        if (executable) {
+          return executable;
+        }
+      }
+    } catch {
+      return null;
+    }
+
+    return null;
+  }
+
+  private findFfmpegExecutableInside(baseDir: string): string | null {
+    const directCandidate = join(baseDir, 'bin', 'ffmpeg.exe');
+    if (existsSync(directCandidate)) {
+      return directCandidate;
+    }
+
+    try {
+      const versionDirs = readdirSync(baseDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && entry.name.toLowerCase().startsWith('ffmpeg-'))
+        .map((entry) => join(baseDir, entry.name))
+        .sort((a, b) => b.localeCompare(a));
+
+      for (const versionDir of versionDirs) {
+        const candidate = join(versionDir, 'bin', 'ffmpeg.exe');
+        if (existsSync(candidate)) {
+          return candidate;
+        }
+      }
+    } catch {
+      return null;
+    }
+
+    return null;
+  }
+
   private getPositiveIntegerEnv(name: string): number | undefined {
     const raw = process.env[name];
     if (!raw) {
@@ -364,6 +1315,21 @@ export class CourseVideoConversionService implements OnModuleInit, IJobHandler {
     return Math.floor(value);
   }
 
+  private resolveFrameIntervalSeconds(value: unknown): number {
+    if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+      return Math.max(1, Math.floor(value));
+    }
+
+    if (typeof value === 'string') {
+      const parsed = Number(value);
+      if (Number.isFinite(parsed) && parsed > 0) {
+        return Math.max(1, Math.floor(parsed));
+      }
+    }
+
+    return 10;
+  }
+
   private calculateMBps(bytes: number, durationMs: number): number {
     if (!Number.isFinite(bytes) || bytes <= 0) {
       return 0;