Skip to main content

Speaker targeting

Use target in report requests to choose which speaker is analyzed.

Strategies​

StrategyUse whenKey fields
dominantone clear primary speakerstrategy
magic_hintrole known in natural languagehint, optional onMiss
entity_idsame speaker tracked across sessionsentityId, optional onMiss
timerangespeaker in specific segmenttimeRange, optional onMiss

Dominant speaker​

const receipt = await mappa.reports.createJob({
  media: { mediaId: "media_abc123" },
  output: { template: "general_report" },
  target: { strategy: "dominant" },
});
const report = await mappa.reports.generateFromUrl({
  url: "https://example.com/interview.mp3",
  output: {
    template: "hiring_report",
    templateParams: {
      roleTitle: "Senior Software Engineer",
      roleDescription: "Backend development",
      companyCulture: "Collaborative",
    },
  },
  target: {
    strategy: "magic_hint",
    hint: "the job candidate being interviewed",
    onMiss: "fallback_dominant",
  },
});

Entity ID (best for continuity)​

const round1 = await mappa.reports.generateFromUrl({
  url: "https://example.com/round-1.mp3",
  output: { template: "general_report" },
  target: { strategy: "magic_hint", hint: "the candidate" },
});

const entityId = round1.entity?.id;
if (!entityId) throw new Error("Entity not found");

const round2 = await mappa.reports.generateFromUrl({
  url: "https://example.com/round-2.mp3",
  output: { template: "hiring_report" },
  target: { strategy: "entity_id", entityId },
});

Time range​

const report = await mappa.reports.generate({
  media: { mediaId: "media_meeting789" },
  output: { template: "general_report" },
  target: {
    strategy: "timerange",
    timeRange: {
      startSeconds: 0,
      endSeconds: 300,
    },
    onMiss: "fallback_dominant",
  },
});

Hint quality​

  • Good: "the interviewer asking questions"
  • Good: "the potential customer or prospect"
  • Avoid: "speaker 1", "the loud one"

Best practices​

  • Default to magic_hint for multi-speaker calls.
  • Store report.entity?.id and switch to entity_id in future sessions.
  • Use onMiss: "fallback_dominant" in production to reduce hard failures.

Next steps​