Skip to main content

Core concepts ⚙️

Understand the key concepts that power Mappa. This will help you build better integrations and avoid common pitfalls.

Why two stages?

Think of it like a photo lab. Developing the film (transcription) takes time, but once it's done, you can print unlimited copies instantly. Same here—process once, generate unlimited reports.

Two-Stage architecture​

Mappa separates media processing from report generation:

Stage 1: media processing (once per file)​

Upload → Transcribe → Detect Speakers → Extract Voiceprints → COMPLETED

What happens:

  • Audio transcribed with speaker diarization
  • Behavioral voiceprints extracted for each speaker
  • Entity records created for tracking

Duration: ~1 minute for 30-minute audio
Status: Track via processingStatus field
Cost: 1 credit per minute of media (see Pricing)

Stage 2: report generation (on demand)​

Select Speaker → Apply Template → Generate Insights → Render Output

What happens:

  • Uses cached transcription and voiceprints
  • AI analyzes based on selected template
  • Returns formatted report

Duration: 10-30 seconds
Status: Track via job status
Cost: 10 credits per report (see Pricing)

Why this matters​

Once media is processed, you can:

  • Generate unlimited reports instantly
  • Analyze different speakers without reprocessing
  • Try different templates on the same media
  • Save credits by reusing processed files

Example:

// Upload once
const file = await mappa.files.upload({ file: "./interview.mp4" });

// Generate multiple reports from same media
const candidateReport = await mappa.reports.generate({
  media: { mediaId: file.mediaId },
  output: { template: "hiring_report" },
  target: { strategy: "magic_hint", hint: "the candidate" },
});

const interviewerReport = await mappa.reports.generate({
  media: { mediaId: file.mediaId },
  output: { template: "general_report" },
  target: { strategy: "magic_hint", hint: "the interviewer" },
});

Processing statuses​

Track media processing with the processingStatus field:

StatusWhat It MeansWhat to Do
PENDINGQueued for processingWait—it'll start soon
PROCESSINGCurrently being processedPoll every 5-10 seconds
COMPLETEDReady for reportsCreate report jobs
FAILEDSomething went wrongCheck processingError

Checking status:

const file = await mappa.files.get(mediaId);

if (file.processingStatus === "COMPLETED") {
  // Ready to go!
  const job = await mappa.reports.createJob({
    media: { mediaId },
    output: { template: "general_report" },
    target: { strategy: "dominant" },
  });
}
SDK Helper

The SDK does not expose a dedicated waitForProcessing() helper. Poll mappa.files.get(mediaId) until processingStatus === "COMPLETED".

Jobs​

A job represents a report generation task. Jobs run asynchronously—create them, then wait for completion.

Job lifecycle​

Create → queued/running → succeeded

Job statuses​

StatusDescription
queuedWaiting to start
runningCurrently generating
succeededReport ready
failedSomething failed
canceledJob was canceled

Monitoring a job:

const job = await mappa.reports.createJob({
  media: { mediaId: "media_123" },
  output: { template: "general_report" },
  target: { strategy: "dominant" },
  webhook: { url: "https://yourapp.com/webhooks/mappa" },
});

// Or poll manually
const handle = job.handle ?? mappa.reports.makeHandle(job.jobId);
const result = await handle.wait();
Production Tip

Use webhooks instead of polling! See Webhooks for real-time notifications.

Reports​

Reports are the final output—behavioral insights in your chosen format.

Output types​

TypeReturnsUse Case
markdownMarkdown stringDisplay in apps, save to database
jsonStructured dataParse programmatically
pdfPDF download URLShare with stakeholders
urlHosted report pageQuick sharing

Templates​

Choose a template based on your use case:

TemplateUse ForParameters
general_reportComprehensive profileNone
sales_playbookSales strategiesNone
hiring_reportRole/culture fitroleTitle, roleDescription, companyCulture
profile_alignmentMatch against idealidealProfile

See Templates Reference →

Speaker targeting​

Multi-speaker recordings need speaker selection. Quick overview:

StrategyWhen to Use
dominantSingle speaker or obvious primary
magic_hintMulti-speaker with known roles (👍 Recommended)
entity_idTracking same person across recordings
timerangeSpecific conversation segments

Example:

{
  target: { 
    strategy: "magic_hint",
    hint: "the job candidate being interviewed"
  }
}

Learn targeting strategies →

Entities​

Mappa creates an entity for each detected speaker—a persistent ID you can track across recordings.

What is an entity?

  • Unique ID (e.g., ent_abc123)
  • Behavioral voiceprint stored by Mappa
  • Reusable across multiple media files

Why use entity IDs?

  • Track same person across interviews/sessions
  • Skip speaker identification
  • Build speaker libraries

Example:

// First interview
const report1 = await mappa.reports.generate({
  target: { strategy: "magic_hint", hint: "the candidate" },
});
const entityId = report1.entity?.id; // "ent_abc123"

// Second interview - use entity ID
const report2 = await mappa.reports.generate({
  target: { strategy: "entity_id", entityId: entityId },
});

Advanced entity management →

Credits​

Credits are Mappa's currency. Media processing costs 1 credit per minute; each report costs 10 credits. See Pricing for details.

How credits work​

Create Job → Reserve → Process → Charge Actual → Release Excess

Your balance:

  • Balance: Total credits
  • Reserved: Locked for active jobs
  • Available: What you can spend now
const { available } = await mappa.credits.getBalance();
console.info(`You can create jobs worth ${available} credits`);

Save credits​

  1. Submit feedback - Get 5 credits back per report (50% of report cost)
  2. Reuse processed media - Generate multiple reports from one file
  3. Track entities - Skip re-analysis for known speakers

Credit optimization strategies →

What's next? 🚀​

Ready to build?

Deep dives: