Speaker targeting

Use target in conduitClient.reports.create(...) to choose which speaker is analyzed.

Strategies

Strategy	Use when	Key fields
dominant	one clear primary speaker	strategy
magic_hint	role known in natural language	hint, optional onMiss
entity_id	same speaker tracked across sessions	entityId, optional onMiss
timerange	speaker in a specific segment	timeRange, optional onMiss
speaker_index	you already know which diarized speaker you want	speakerIndex, optional onMiss

Dominant speaker

const receipt = await conduitClient.reports.create({
  source: { mediaId: "media_abc123" },
  output: { template: "general_report" },
  target: { strategy: "dominant" },
})

Magic hint

const receipt = await conduitClient.reports.create({
  source: { url: "https://example.com/interview.mp3" },
  output: {
    template: "general_report",
    templateParams: {
      roleTitle: "Senior Software Engineer",
      roleDescription: "Backend development",
      companyCulture: "Collaborative",
    },
  },
  target: {
    strategy: "magic_hint",
    hint: "the job candidate being interviewed",
    onMiss: "fallback_dominant",
  },
  webhook: { url: "https://your-app.com/webhooks/conduit" },
})

Entity ID

const round1Receipt = await conduitClient.reports.create({
  source: { url: "https://example.com/round-1.mp3" },
  output: { template: "general_report" },
  target: { strategy: "magic_hint", hint: "the candidate" },
})

const round1 = await round1Receipt.handle?.wait()
const entityId = round1?.entity?.id
if (!entityId) throw new Error("Entity not found")

const round2Receipt = await conduitClient.reports.create({
  source: { url: "https://example.com/round-2.mp3" },
  output: { template: "general_report" },
  target: { strategy: "entity_id", entityId },
})

Time range

const receipt = await conduitClient.reports.create({
  source: { mediaId: "media_meeting789" },
  output: { template: "general_report" },
  target: {
    strategy: "timerange",
    timeRange: {
      startSeconds: 0,
      endSeconds: 300,
    },
    onMiss: "fallback_dominant",
  },
})

Speaker index

Upload the media first, read its diarized speakers, then target one by index.

const media = await conduitClient.primitives.media.upload({ path: "./call.mp3" })
const summary = await conduitClient.primitives.media.speakers(media.mediaId)

// status is "processing" until diarization finishes, then "ready" (or "failed")
for (const speaker of summary.speakers) {
  console.info(speaker.speakerIndex, speaker.speechSeconds, speaker.transcript)
}

const receipt = await conduitClient.reports.create({
  source: { mediaId: media.mediaId },
  output: { template: "general_report" },
  target: { strategy: "speaker_index", speakerIndex: 0 },
})

transcript is everything that speaker said across the recording, joined into one string. Speaker indexes belong to one media file; they are not stable across uploads, so use entity_id to follow the same person across sessions.

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" only when best-effort fallback is acceptable.

Next steps

• Entity management
• Production workflow
• Node reports resource