@hed-hog/lms 0.0.365 → 0.0.366

package/hedhog/table/lesson_view_event.yaml

@@ -0,0 +1,66 @@
+columns:
+  - type: pk
+  - name: user_id
+    type: int
+    isNullable: true
+  - name: course_lesson_id
+    type: fk
+    isNullable: true
+    references:
+      table: course_lesson
+      column: id
+      onDelete: SET NULL
+  - name: course_enrollment_id
+    type: fk
+    isNullable: true
+    references:
+      table: course_enrollment
+      column: id
+      onDelete: SET NULL
+  - name: session_id
+    type: varchar
+    length: 36
+    isNullable: true
+  - name: video_position_seconds
+    type: int
+    default: 0
+  - name: ip
+    type: varchar
+    length: 45
+    isNullable: true
+  - name: country
+    type: varchar
+    length: 2
+    isNullable: true
+  - name: city
+    type: varchar
+    length: 100
+    isNullable: true
+  - name: browser
+    type: varchar
+    length: 50
+    isNullable: true
+  - name: os
+    type: varchar
+    length: 50
+    isNullable: true
+  - name: device_type
+    type: varchar
+    length: 20
+    isNullable: true
+  - name: screen_width
+    type: int
+    isNullable: true
+  - name: screen_height
+    type: int
+    isNullable: true
+  - name: is_touch
+    type: boolean
+    default: false
+  - type: created_at
+
+indices:
+  - columns: [user_id, created_at]
+  - columns: [course_lesson_id, created_at]
+  - columns: [created_at]
+  - columns: [course_enrollment_id]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hed-hog/lms",
-  "version": "0.0.365",
+  "version": "0.0.366",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
@@ -16,14 +16,15 @@
     "@hed-hog/api-prisma": "0.0.6",
     "@hed-hog/api-locale": "0.0.14",
     "@hed-hog/api-pagination": "0.0.7",
-    "@hed-hog/api-types": "0.0.1",
-    "@hed-hog/category": "0.0.365",
-    "@hed-hog/crm": "0.0.365",
     "@hed-hog/api": "0.0.8",
-    "@hed-hog/finance": "0.0.365",
-    "@hed-hog/commerce": "0.0.365",
-    "@hed-hog/queue": "0.0.365",
-    "@hed-hog/core": "0.0.365"
+    "@hed-hog/category": "0.0.366",
+    "@hed-hog/api-types": "0.0.1",
+    "@hed-hog/crm": "0.0.366",
+    "@hed-hog/finance": "0.0.366",
+    "@hed-hog/core": "0.0.366",
+    "@hed-hog/queue": "0.0.366",
+    "@hed-hog/commerce": "0.0.366",
+    "@hed-hog/agent": "0.0.366"
   },
   "exports": {
     ".": {

package/src/course/course-structure.controller.ts

@@ -10,6 +10,7 @@ import {
     Post,
 } from '@nestjs/common';
 import { CourseStructureService } from './course-structure.service';
+import { CourseVideoAgentPipelineService } from './course-video-agent-pipeline.service';
 import { CourseVideoConversionService } from './course-video-conversion.service';
 import { CourseVideoHlsService } from './course-video-hls.service';
 import { CreateCourseBulkJobDto } from './dto/create-course-bulk-job.dto';
@@ -35,6 +36,7 @@ export class CourseStructureController {
     private readonly courseStructureService: CourseStructureService,
     private readonly courseVideoConversionService: CourseVideoConversionService,
     private readonly courseVideoHlsService: CourseVideoHlsService,
+    private readonly courseVideoAgentPipelineService: CourseVideoAgentPipelineService,
   ) {}
 
   @Get()
@@ -162,7 +164,7 @@ export class CourseStructureController {
     @Param('lessonId', ParseIntPipe) lessonId: number,
     @Body() dto: CreateLessonVideoConversionDto,
   ) {
-    return this.courseVideoHlsService.enqueueHls({
+    return this.courseVideoAgentPipelineService.startProcessing({
       userId,
       courseId,
       sessionId,

package/src/course/course-video-agent-pipeline.service.ts

@@ -0,0 +1,471 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import { buildAiConfigFromIntegration, FileService, SettingService } from '@hed-hog/core';
+import {
+  DatabaseQueueProvider,
+  IJobHandler,
+  NonRetryableError,
+  QueueHandlerRegistry,
+} from '@hed-hog/queue';
+import { AgentRuntimeService } from '@hed-hog/agent';
+import { Inject, Injectable, Logger, OnModuleInit, forwardRef } from '@nestjs/common';
+import axios from 'axios';
+import { execFile } from 'child_process';
+import { promises as fs } from 'fs';
+import { tmpdir } from 'os';
+import { basename, join } from 'path';
+import { promisify } from 'util';
+import { CourseVideoHlsService } from './course-video-hls.service';
+import { getFfmpegCommand } from './ffmpeg.util';
+
+const execFileAsync = promisify(execFile);
+
+export const VIDEO_PROCESSING_AGENT_SLUG = 'lms-video-processing';
+
+export const LMS_AUDIO_EXTRACT_JOB = 'lms.audio.extract';
+export const LMS_AUDIO_SPLIT_JOB = 'lms.audio.split';
+export const LMS_AUDIO_TRANSCRIBE_CHUNKS_JOB = 'lms.audio.transcribe.chunks';
+export const LMS_TRANSCRIPTION_SAVE_JOB = 'lms.transcription.save';
+
+const CHUNK_SECONDS = 60;
+
+type JobInput = {
+  id: number;
+  type: string;
+  queue_name: string;
+  payload: Record<string, any>;
+  attempts: number;
+  max_attempts: number;
+};
+
+/**
+ * Decomposed, queue-backed steps of the LMS video transcription pipeline, orchestrated by the
+ * seeded `lms-video-processing` agent flow via `tool.queue_dispatch` (dispatch-and-wait).
+ *
+ * Each step is its own job so it is visible both in the queue dashboard and the agent run
+ * timeline. Intermediates are persisted (audio + chunk + transcript files) and only small
+ * file-id references travel through the agent state between steps. The existing monolithic
+ * `lms.audio.transcribe` job and legacy paths are left untouched.
+ */
+@Injectable()
+export class CourseVideoAgentPipelineService implements OnModuleInit, IJobHandler {
+  private readonly logger = new Logger(CourseVideoAgentPipelineService.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(() => QueueHandlerRegistry))
+    private readonly registry: QueueHandlerRegistry,
+    @Inject(forwardRef(() => DatabaseQueueProvider))
+    private readonly dbQueue: DatabaseQueueProvider,
+    @Inject(forwardRef(() => AgentRuntimeService))
+    private readonly agentRuntime: AgentRuntimeService,
+    @Inject(forwardRef(() => CourseVideoHlsService))
+    private readonly hlsService: CourseVideoHlsService,
+  ) {}
+
+  private get db() {
+    return this.prisma as any;
+  }
+
+  onModuleInit() {
+    for (const type of [
+      LMS_AUDIO_EXTRACT_JOB,
+      LMS_AUDIO_SPLIT_JOB,
+      LMS_AUDIO_TRANSCRIBE_CHUNKS_JOB,
+      LMS_TRANSCRIPTION_SAVE_JOB,
+    ]) {
+      this.registry.register(type, this);
+    }
+    this.logger.log(
+      `Registered handlers for ${LMS_AUDIO_EXTRACT_JOB}, ${LMS_AUDIO_SPLIT_JOB}, ${LMS_AUDIO_TRANSCRIBE_CHUNKS_JOB}, ${LMS_TRANSCRIPTION_SAVE_JOB}`,
+    );
+  }
+
+  // ───────────────────────────── orchestration entry ─────────────────────────────
+
+  /**
+   * Validates the lesson/original, registers the `video_original` file, and starts the seeded
+   * `lms-video-processing` agent run (async). Falls back to the legacy monolithic HLS pipeline
+   * when the agent flow is not seeded yet, so the feature degrades gracefully during rollout.
+   */
+  async startProcessing(params: {
+    userId: number;
+    courseId: number;
+    sessionId: number;
+    lessonId: number;
+    originalFileId: number;
+  }): Promise<{ agentRunId: number | null; status: string }> {
+    const agent = await this.db.agent.findUnique({
+      where: { slug: VIDEO_PROCESSING_AGENT_SLUG },
+      select: { id: true, status: true },
+    });
+
+    if (!agent || agent.status === 'archived') {
+      this.logger.warn(
+        `Agent "${VIDEO_PROCESSING_AGENT_SLUG}" unavailable — falling back to legacy enqueueHls.`,
+      );
+      const legacy = await this.hlsService.enqueueHls(params);
+      return { agentRunId: null, status: legacy.status };
+    }
+
+    await this.hlsService.prepareLessonForProcessing({
+      courseId: params.courseId,
+      sessionId: params.sessionId,
+      lessonId: params.lessonId,
+      originalFileId: params.originalFileId,
+    });
+
+    const settings = await this.settingService.getSettingValues([
+      'lms-audio-transcription-enabled',
+    ]);
+    const transcriptionEnabled = settings['lms-audio-transcription-enabled'] !== false;
+
+    const course = await this.db.course.findUnique({
+      where: { id: params.courseId },
+      include: { locale: true },
+    });
+    const localeCode = course?.locale?.code ?? 'pt';
+
+    const run = await this.agentRuntime.startManualRun(
+      agent.id,
+      {
+        course_id: params.courseId,
+        session_id: params.sessionId,
+        lesson_id: params.lessonId,
+        original_file_id: params.originalFileId,
+        user_id: params.userId,
+        transcription_enabled: transcriptionEnabled,
+        locale_code: localeCode,
+      },
+      params.userId,
+    );
+
+    this.logger.log(
+      `Started agent run ${run?.id} for lesson ${params.lessonId} (transcription=${transcriptionEnabled}).`,
+    );
+    return { agentRunId: run?.id ?? null, status: 'started' };
+  }
+
+  // ───────────────────────────── job dispatch ─────────────────────────────
+
+  async handle(job: JobInput): Promise<any> {
+    switch (job.type) {
+      case LMS_AUDIO_EXTRACT_JOB:
+        return this.handleExtract(job);
+      case LMS_AUDIO_SPLIT_JOB:
+        return this.handleSplit(job);
+      case LMS_AUDIO_TRANSCRIBE_CHUNKS_JOB:
+        return this.handleTranscribeChunks(job);
+      case LMS_TRANSCRIPTION_SAVE_JOB:
+        return this.handleSave(job);
+      default:
+        throw new NonRetryableError(`Unsupported job type "${job.type}"`);
+    }
+  }
+
+  /** Step: extract a 16 kHz mono mp3 from the original video and persist it as lesson_audio. */
+  private async handleExtract(job: JobInput): Promise<{ audioFileId: number }> {
+    const courseId = Number(job.payload?.courseId);
+    const lessonId = Number(job.payload?.lessonId);
+    const originalFileId = Number(job.payload?.originalFileId);
+    if (!lessonId || !originalFileId) {
+      throw new NonRetryableError('lms.audio.extract: lessonId and originalFileId are required.');
+    }
+
+    const workDir = await fs.mkdtemp(join(tmpdir(), `lms-extract-${job.id}-`));
+    const inputPath = join(workDir, `original-${originalFileId}`);
+    const mp3Path = join(workDir, `lesson_${lessonId}_audio.mp3`);
+    try {
+      await this.fileService.downloadToPath(originalFileId, inputPath);
+      await execFileAsync(
+        getFfmpegCommand(),
+        ['-y', '-i', inputPath, '-vn', '-ar', '16000', '-ac', '1', '-c:a', 'libmp3lame', '-b:a', '32k', mp3Path],
+        { maxBuffer: 1024 * 1024 * 20, windowsHide: true },
+      );
+
+      const course = await this.db.course.findUnique({
+        where: { id: 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.db.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.db.course_lesson_file.findFirst({
+        where: { course_lesson_id: lessonId, type: 'lesson_audio' },
+        select: { id: true },
+      });
+      if (existing) {
+        await this.db.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.db.course_lesson_file.create({
+          data: { course_lesson_id: lessonId, file_id: uploaded.id, title: 'Audio Original.mp3', type: 'lesson_audio', is_public: false, locale_id: resolvedLocaleId },
+        });
+      }
+
+      this.logger.log(`[extract job=${job.id}] lesson ${lessonId} audio fileId=${uploaded.id}`);
+      return { audioFileId: uploaded.id };
+    } finally {
+      await fs.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+  }
+
+  /** Step: split the lesson audio into 60s chunks, uploaded to a staging prefix. */
+  private async handleSplit(
+    job: JobInput,
+  ): Promise<{ chunkFileIds: number[]; chunkCount: number }> {
+    const lessonId = Number(job.payload?.lessonId);
+    const audioFileId = Number(job.payload?.audioFileId);
+    if (!lessonId || !audioFileId) {
+      throw new NonRetryableError('lms.audio.split: lessonId and audioFileId are required.');
+    }
+
+    const workDir = await fs.mkdtemp(join(tmpdir(), `lms-split-${job.id}-`));
+    const sourceAudioPath = join(workDir, `audio_${lessonId}.source`);
+    const normalizedAudioPath = join(workDir, `audio_${lessonId}.normalized.mp3`);
+    try {
+      await this.fileService.downloadToPath(audioFileId, sourceAudioPath);
+      await execFileAsync(
+        getFfmpegCommand(),
+        ['-y', '-i', sourceAudioPath, '-ar', '16000', '-ac', '1', '-c:a', 'libmp3lame', '-b:a', '32k', normalizedAudioPath],
+        { maxBuffer: 1024 * 1024 * 20, windowsHide: true },
+      );
+
+      const chunkPattern = join(workDir, 'chunk_%04d.mp3');
+      await execFileAsync(
+        getFfmpegCommand(),
+        ['-y', '-i', normalizedAudioPath, '-f', 'segment', '-segment_time', String(CHUNK_SECONDS), '-ar', '16000', '-ac', '1', '-c:a', 'libmp3lame', '-b:a', '32k', chunkPattern],
+        { maxBuffer: 1024 * 1024 * 20, windowsHide: true },
+      );
+
+      const chunkNames = (await fs.readdir(workDir))
+        .filter((n) => n.startsWith('chunk_') && n.endsWith('.mp3'))
+        .sort((a, b) => a.localeCompare(b));
+
+      const chunkFileIds: number[] = [];
+      for (const name of chunkNames) {
+        const uploaded = await this.fileService.uploadFromPath(
+          `lms/lessons/transcribe-chunks/${lessonId}`,
+          join(workDir, name),
+          { originalname: name, mimetype: 'audio/mpeg' },
+        );
+        chunkFileIds.push(uploaded.id);
+      }
+
+      this.logger.log(`[split job=${job.id}] lesson ${lessonId} → ${chunkFileIds.length} chunk(s)`);
+      return { chunkFileIds, chunkCount: chunkFileIds.length };
+    } finally {
+      await fs.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+  }
+
+  /** Step: transcribe each chunk via OpenAI Whisper and persist the merged transcript JSON. */
+  private async handleTranscribeChunks(
+    job: JobInput,
+  ): Promise<{ transcriptFileId: number; segmentCount: number }> {
+    const courseId = Number(job.payload?.courseId);
+    const lessonId = Number(job.payload?.lessonId);
+    const chunkFileIds = this.parseIdArray(job.payload?.chunkFileIds);
+    if (!lessonId || chunkFileIds.length === 0) {
+      throw new NonRetryableError('lms.audio.transcribe.chunks: lessonId and chunkFileIds are required.');
+    }
+
+    const apiKey = await this.resolveOpenAiKey();
+    const course = await this.db.course.findUnique({
+      where: { id: courseId },
+      include: { locale: true },
+    });
+    const language = course?.locale?.code ?? 'pt';
+
+    const workDir = await fs.mkdtemp(join(tmpdir(), `lms-transcribe-${job.id}-`));
+    try {
+      const segments: Array<{
+        course_lesson_id: number;
+        start_seconds: number;
+        end_seconds: number;
+        text: string;
+      }> = [];
+
+      for (let i = 0; i < chunkFileIds.length; i += 1) {
+        const chunkPath = join(workDir, `chunk_${i}.mp3`);
+        await this.fileService.downloadToPath(chunkFileIds[i], chunkPath);
+        const offsetSeconds = i * CHUNK_SECONDS;
+        const buffer = await fs.readFile(chunkPath);
+
+        const formData = new FormData();
+        formData.append('file', new Blob([buffer], { type: 'audio/mpeg' }), `chunk_${i}.mp3`);
+        formData.append('model', 'whisper-1');
+        formData.append('response_format', 'verbose_json');
+        formData.append('language', language);
+
+        const headers: Record<string, string> = { Authorization: `Bearer ${apiKey}` };
+        const maybeHeaders = (formData as any).getHeaders?.();
+        if (maybeHeaders && typeof maybeHeaders === 'object') Object.assign(headers, maybeHeaders);
+
+        const response = await axios.post(
+          'https://api.openai.com/v1/audio/transcriptions',
+          formData,
+          { headers },
+        );
+
+        for (const segment of response.data?.segments ?? []) {
+          const text = String(segment?.text ?? '').trim();
+          if (!text) continue;
+          segments.push({
+            course_lesson_id: lessonId,
+            start_seconds: offsetSeconds + Number(segment?.start ?? 0),
+            end_seconds: offsetSeconds + Number(segment?.end ?? 0),
+            text,
+          });
+        }
+      }
+
+      const transcriptPath = join(workDir, `transcript_${lessonId}.json`);
+      await fs.writeFile(transcriptPath, JSON.stringify({ lessonId, segments }), 'utf8');
+      const uploaded = await this.fileService.uploadFromPath(
+        `lms/lessons/transcripts/${lessonId}`,
+        transcriptPath,
+        { originalname: `transcript_${lessonId}.json`, mimetype: 'application/json' },
+      );
+
+      this.logger.log(`[transcribe job=${job.id}] lesson ${lessonId} → ${segments.length} segment(s)`);
+      return { transcriptFileId: uploaded.id, segmentCount: segments.length };
+    } finally {
+      await fs.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+  }
+
+  /** Step: join + persist the transcript segments and trigger XP calculation. */
+  private async handleSave(job: JobInput): Promise<{ saved: number }> {
+    const lessonId = Number(job.payload?.lessonId);
+    const transcriptFileId = Number(job.payload?.transcriptFileId);
+    const userId = Number(job.payload?.userId) || 0;
+    if (!lessonId || !transcriptFileId) {
+      throw new NonRetryableError('lms.transcription.save: lessonId and transcriptFileId are required.');
+    }
+
+    const workDir = await fs.mkdtemp(join(tmpdir(), `lms-tsave-${job.id}-`));
+    try {
+      const transcriptPath = join(workDir, 'transcript.json');
+      await this.fileService.downloadToPath(transcriptFileId, transcriptPath);
+      const parsed = JSON.parse(await fs.readFile(transcriptPath, 'utf8'));
+      const segments: Array<Record<string, any>> = Array.isArray(parsed?.segments)
+        ? parsed.segments
+        : [];
+
+      await this.prisma.$transaction([
+        this.db.course_lesson_transcription_segment.deleteMany({
+          where: { course_lesson_id: lessonId },
+        }),
+        this.db.course_lesson_transcription_segment.createMany({
+          data: segments.map((s) => ({
+            course_lesson_id: lessonId,
+            start_seconds: Number(s?.start_seconds ?? 0),
+            end_seconds: Number(s?.end_seconds ?? 0),
+            text: String(s?.text ?? ''),
+          })),
+        }),
+      ]);
+
+      this.logger.log(`[save job=${job.id}] lesson ${lessonId} saved ${segments.length} segment(s)`);
+      await this.triggerXpCalculation(lessonId, userId);
+      return { saved: segments.length };
+    } finally {
+      await fs.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+  }
+
+  // ───────────────────────────── helpers ─────────────────────────────
+
+  private parseIdArray(raw: unknown): number[] {
+    let arr: unknown = raw;
+    if (typeof raw === 'string') {
+      try {
+        arr = JSON.parse(raw);
+      } catch {
+        arr = [];
+      }
+    }
+    if (!Array.isArray(arr)) return [];
+    return arr.map((x) => Number(x)).filter((n) => Number.isFinite(n) && n > 0);
+  }
+
+  private async resolveOpenAiKey(): Promise<string> {
+    const settings = await this.settingService.getSettingValues(['ai-openai-profile-id']);
+    const profileId = Number(settings['ai-openai-profile-id']);
+    let apiKey = '';
+    if (profileId) {
+      const profile = await this.db.integration_profile.findUnique({
+        where: { id: profileId },
+        include: { integration_provider: { select: { slug: true } } },
+      });
+      if (profile) {
+        apiKey = buildAiConfigFromIntegration(profile.integration_provider.slug, profile.config).apiKey;
+      }
+    }
+    if (!apiKey) {
+      throw new NonRetryableError(
+        'Transcrição de áudio requer um perfil OpenAI configurado (Settings → LMS → ai-openai-profile-id).',
+      );
+    }
+    return apiKey;
+  }
+
+  private async triggerXpCalculation(lessonId: number, userId: number): Promise<void> {
+    try {
+      const existingMap = await this.db.lesson_xp_map.findUnique({
+        where: { course_lesson_id: lessonId },
+        select: { id: true },
+      });
+
+      let mapId: number;
+      if (existingMap) {
+        mapId = existingMap.id;
+        await this.prisma.$executeRawUnsafe(
+          `UPDATE lesson_xp_map
+              SET status = 'processing'::lesson_xp_map_status_d4e5f6a7b8_enum,
+                  processing_error = NULL,
+                  updated_at = NOW()
+            WHERE id = $1`,
+          mapId,
+        );
+      } else {
+        const rows = await this.prisma.$queryRawUnsafe<{ id: number }[]>(
+          `INSERT INTO lesson_xp_map (course_lesson_id, version, total_xp, status, created_at, updated_at)
+           VALUES ($1, 1, 0, 'processing'::lesson_xp_map_status_d4e5f6a7b8_enum, NOW(), NOW())
+           RETURNING id`,
+          lessonId,
+        );
+        mapId = rows[0].id;
+      }
+
+      await this.dbQueue.enqueue({
+        type: 'lms.lesson.xp.calculate',
+        queueName: 'lms.lesson.xp.calculate',
+        payload: { lessonId, mapId, userId },
+        maxAttempts: 3,
+        sourceModule: 'lms',
+        sourceEntity: 'course_lesson',
+        sourceEntityId: String(lessonId),
+      });
+    } catch (err) {
+      this.logger.warn(
+        `Failed to enqueue XP calculation for lesson ${lessonId}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+}

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

@@ -70,13 +70,17 @@ export class CourseVideoHlsService implements OnModuleInit, IJobHandler {
     this.logger.log(`Registered handler for "${LMS_VIDEO_HLS_JOB}"`);
   }
 
-  async enqueueHls(params: {
-    userId: number;
+  /**
+   * Validates a lesson is an eligible file-storage video and registers the uploaded original
+   * as its `video_original` file. Shared by the legacy `enqueueHls` path and the new
+   * agent-orchestrated pipeline (CourseVideoAgentPipelineService.startProcessing).
+   */
+  async prepareLessonForProcessing(params: {
     courseId: number;
     sessionId: number;
     lessonId: number;
     originalFileId: number;
-  }) {
+  }): Promise<{ content: Record<string, unknown> | null; original: any }> {
     const lesson = await (this.prisma as any).course_lesson.findFirst({
       where: {
         id: params.lessonId,
@@ -118,6 +122,18 @@ export class CourseVideoHlsService implements OnModuleInit, IJobHandler {
       overwrite: true,
     });
 
+    return { content, original };
+  }
+
+  async enqueueHls(params: {
+    userId: number;
+    courseId: number;
+    sessionId: number;
+    lessonId: number;
+    originalFileId: number;
+  }) {
+    const { content } = await this.prepareLessonForProcessing(params);
+
     const asyncNotification = await this.notificationService.create({
       user_id: params.userId,
       title: 'Geração de HLS em andamento',
@@ -189,12 +205,16 @@ export class CourseVideoHlsService implements OnModuleInit, IJobHandler {
     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;
-    };
+    // Ids are coerced because agent-dispatched payloads template values as strings.
+    const courseId = Number(job.payload?.courseId);
+    const sessionId = Number(job.payload?.sessionId);
+    const lessonId = Number(job.payload?.lessonId);
+    const originalFileId = Number(job.payload?.originalFileId);
+    // Set by the agent pipeline: HLS-only, since audio extraction + transcription are
+    // dispatched as their own visible steps. Legacy callers omit it (full behaviour).
+    const skipAudioTranscription =
+      job.payload?.skipAudioTranscription === true ||
+      job.payload?.skipAudioTranscription === 'true';
 
     const notificationContext: NotificationContext | undefined =
       Number.isInteger(Number(job.payload?.notificationId)) &&
@@ -359,7 +379,7 @@ export class CourseVideoHlsService implements OnModuleInit, IJobHandler {
         this.logger.debug(`[HLS job=${job.id}] frame extraction disabled — skipping`);
       }
 
-      if (transcriptionEnabled) {
+      if (transcriptionEnabled && !skipAudioTranscription) {
         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({