"""
Bulk Transcription Analysis Tool
This script helps you:
1. Fetch multiple transcription results from the CAMB.AI API
2. Analyze the transcriptions (duration, speakers, content)
3. Export transcriptions to CSV files
4. Find common speakers and words across all transcriptions
Before running:
- Replace "your-api-key" with your actual API key
- Install required packages: pip install requests
"""
import requests
import csv
from collections import Counter
import re
# ============================================================================
# CONFIGURATION - Update these values before running
# ============================================================================
# Your API authentication details
headers = {
"x-api-key": "your-api-key", # 🔑 REPLACE WITH YOUR ACTUAL API KEY
"Content-Type": "application/json",
}
# The API endpoint for fetching transcription results
API_URL = "https://client.camb.ai/apis/transcription-results"
# ============================================================================
# MAIN FUNCTIONS
# ============================================================================
def get_bulk_transcriptions(run_ids):
"""
Fetches multiple transcription results from the API in a single request.
This function sends a list of run IDs to the API and gets back all the
transcription data for those runs at once, which is much faster than
making individual requests for each run.
Parameters:
run_ids (list): A list of numbers representing the run IDs you want to fetch
Example: [12345, 12346, 12347]
Returns:
dict: A dictionary where each key is a run ID and each value contains
the transcription data for that run. Returns None if there's an error.
Example response structure:
{
"12345": {
"transcript": [
{"start": 0.0, "end": 2.5, "speaker": "Speaker_1", "text": "Hello world"},
{"start": 2.5, "end": 5.0, "speaker": "Speaker_2", "text": "How are you?"}
]
}
}
"""
try:
# Prepare the data to send to the API
payload = {"run_ids": run_ids}
print(f"📡 Requesting transcriptions for {len(run_ids)} runs...")
# Make the API request
response = requests.post(
API_URL,
headers=headers,
json=payload,
)
# Check if the request was successful (status code 200-299)
response.raise_for_status()
# Convert the response from JSON to a Python dictionary
results = response.json()
# Show the raw response for debugging (you can comment this out later)
print("📋 Raw API response:")
print(results)
print()
print(f"✅ Successfully retrieved {len(results)} transcription results")
return results
except requests.exceptions.RequestException as e:
# This handles network errors, API errors, etc.
print(f"❌ Error retrieving bulk transcriptions: {e}")
if hasattr(e, "response") and e.response is not None:
print(f"🔍 Response details: {e.response.text}")
return None
# ============================================================================
# HELPER FUNCTIONS
# ============================================================================
def format_time(seconds):
"""
Converts seconds to a readable HH:MM:SS format.
Parameters:
seconds (float): Time in seconds (e.g., 3661.5)
Returns:
str: Formatted time string (e.g., "01:01:01")
"""
hours = int(seconds // 3600) # Get whole hours
minutes = int((seconds % 3600) // 60) # Get remaining minutes
secs = int(seconds % 60) # Get remaining seconds
# Format with leading zeros (e.g., "01:05:30" instead of "1:5:30")
return f"{hours:02d}:{minutes:02d}:{secs:02d}"
def safe_get_transcript(transcription_data):
"""
Safely extracts the transcript from API response data.
The API returns nested data, so we need to safely navigate to the transcript.
Parameters:
transcription_data (dict): The data for one transcription run
Returns:
list: List of transcript segments, or empty list if not found
"""
if not transcription_data:
return []
# Navigate safely: transcription_data -> "transcript" -> list of segments
return transcription_data.get("transcript", [])
# ============================================================================
# ANALYSIS FUNCTIONS
# ============================================================================
def analyze_single_transcription(transcription, run_id):
"""
Analyzes a single transcription and prints detailed statistics.
This function examines one transcription result and shows:
- How long the audio was
- How many dialogue segments there are
- Who the speakers are
- Sample dialogue from the beginning
Parameters:
transcription (list): List of dialogue segments from the API
run_id (str): The ID of this transcription run (for display purposes)
"""
# Check if we have any data to analyze
if not transcription:
print(f"🔍 Run {run_id}: No transcription data available")
return
print(f"📊 Analyzing Run {run_id}:")
print("=" * 40)
# Calculate basic statistics
total_duration = max(segment["end"] for segment in transcription) if transcription else 0
total_segments = len(transcription)
# Find all unique speakers in this transcription
speakers = set()
for segment in transcription:
if "speaker" in segment:
speakers.add(segment["speaker"])
unique_speakers = len(speakers)
# Count how many times each speaker appears
speaker_counts = Counter()
for segment in transcription:
if "speaker" in segment:
speaker_counts[segment["speaker"]] += 1
# Find who spoke the most
most_frequent_speaker = speaker_counts.most_common(1)[0][0] if speaker_counts else "Unknown"
# Print all the statistics
print(f" 🕐 Total duration: {format_time(total_duration)}")
print(f" 💬 Total segments: {total_segments}")
print(f" 👥 Unique speakers: {unique_speakers}")
print(f" 🎤 Most frequent speaker: {most_frequent_speaker}")
# Show the first few lines of dialogue as examples
print(" 📝 Sample dialogue:")
for i, segment in enumerate(transcription[:2]): # Show first 2 segments only
start_time = format_time(segment["start"])
end_time = format_time(segment["end"])
speaker = segment.get("speaker", "Unknown")
# Truncate long text to keep output readable
text = segment.get("text", "")
if len(text) > 50:
text = text[:50] + "..."
print(f" [{start_time} → {end_time}] {speaker}: {text}")
print() # Add blank line for readability
def analyze_bulk_transcriptions(transcription_results):
"""
Analyzes all transcription results and provides insights for each one.
This is the main analysis function that processes all the transcriptions
you fetched from the API.
Parameters:
transcription_results (dict): Dictionary of all transcription results from the API
"""
if not transcription_results:
print("❌ No transcription results to analyze")
return
print(f"\n🔍 Analyzing {len(transcription_results)} transcription results:")
print("=" * 60)
# Process each transcription one by one
for run_id in transcription_results:
# Safely extract the transcript data
transcript = safe_get_transcript(transcription_results.get(run_id, {}))
# Analyze this individual transcription
analyze_single_transcription(transcript, run_id)
# ============================================================================
# EXPORT FUNCTIONS
# ============================================================================
def export_transcription_to_csv(transcription, filename):
"""
Export a single transcription to a CSV file for further analysis.
Creates a CSV file with columns: start, end, speaker, text
This makes it easy to open in Excel or other spreadsheet programs.
Parameters:
transcription (list): List of dialogue segments
filename (str): Name of the output file (e.g., "transcription_12345.csv")
"""
if not transcription:
print(f"⚠️ No data to export for {filename}")
return
try:
# Open the file for writing
with open(filename, "w", newline="", encoding="utf-8") as csvfile:
# Define the column headers
fieldnames = ["start", "end", "speaker", "text"]
writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
# Write the header row
writer.writeheader()
# Write each dialogue segment as a row
for segment in transcription:
writer.writerow({
"start": segment.get("start", ""),
"end": segment.get("end", ""),
"speaker": segment.get("speaker", ""),
"text": segment.get("text", ""),
})
print(f"💾 Exported transcription to {filename}")
except Exception as e:
print(f"❌ Error exporting to {filename}: {e}")
# ============================================================================
# CROSS-TRANSCRIPTION ANALYSIS FUNCTIONS
# ============================================================================
def extract_speakers_from_bulk(transcription_results):
"""
Finds all unique speakers across multiple transcription runs.
This helps you understand who appears in your audio content overall.
Parameters:
transcription_results (dict): Dictionary of all transcription results
Returns:
list: List of all unique speaker names found across all transcriptions
"""
all_speakers = set() # Use a set to automatically handle duplicates
# Go through each transcription
for run_id in transcription_results:
transcript = safe_get_transcript(transcription_results.get(run_id, {}))
if transcript:
# Extract speakers from this transcription
for segment in transcript:
if "speaker" in segment:
all_speakers.add(segment["speaker"])
return list(all_speakers) # Convert back to list
def find_common_words(transcription_results, min_length=5):
"""
Identifies frequently used words across multiple transcriptions.
This helps you understand the main topics and themes in your audio content.
Parameters:
transcription_results (dict): Dictionary of all transcription results
min_length (int): Minimum word length to consider (default: 5)
This filters out common short words like "the", "and", etc.
Returns:
Counter: A Counter object with word frequencies
"""
all_words = []
# Go through each transcription
for run_id in transcription_results:
transcript = safe_get_transcript(transcription_results.get(run_id, {}))
if transcript:
# Extract words from each dialogue segment
for segment in transcript:
if "text" in segment:
# Convert to lowercase for consistent counting
text = segment["text"].lower()
# Extract words (letters only, no punctuation)
words = re.findall(r"\b\w+\b", text)
# Only keep words that are long enough
filtered_words = [word for word in words if len(word) >= min_length]
all_words.extend(filtered_words)
# Count how many times each word appears
word_counts = Counter(all_words)
# Display the results
print("\n📈 Most common words across all transcriptions:")
print("-" * 45)
for word, count in word_counts.most_common(10): # Show top 10
print(f" {word}: {count} occurrences")
return word_counts
# ============================================================================
# MAIN EXECUTION
# ============================================================================
if __name__ == "__main__":
"""
Main execution section - this runs when you execute the script directly.
Modify the run_ids list below with your actual run IDs.
"""
print("🚀 Starting Bulk Transcription Analysis Tool")
print("=" * 50)
# ⚠️ MODIFY THIS LIST WITH YOUR ACTUAL RUN IDs
run_ids = [12345, 12346, 12347, 12348]
print(f"📋 Processing run IDs: {run_ids}")
print()
# Step 1: Fetch all transcription results from the API
print("🔄 Step 1: Fetching transcription results...")
bulk_results = get_bulk_transcriptions(run_ids)
if bulk_results:
print("✅ Successfully fetched results. Starting analysis...")
# Step 2: Analyze all transcription results
print("\n🔄 Step 2: Analyzing transcriptions...")
analyze_bulk_transcriptions(bulk_results)
# Step 3: Export each transcription to a separate CSV file
print("\n🔄 Step 3: Exporting transcriptions to CSV files...")
for run_id in bulk_results:
transcript = safe_get_transcript(bulk_results.get(run_id, {}))
if transcript:
filename = f"transcription_run_{run_id}.csv"
export_transcription_to_csv(transcript, filename)
# Step 4: Find all speakers across all transcriptions
print("\n🔄 Step 4: Finding all speakers...")
all_speakers = extract_speakers_from_bulk(bulk_results)
print(f"👥 All speakers across {len(bulk_results)} runs: {all_speakers}")
# Step 5: Analyze common vocabulary
print("\n🔄 Step 5: Analyzing common vocabulary...")
find_common_words(bulk_results)
print("\n🎉 Analysis complete! Check the CSV files for detailed transcription data.")
else:
print("❌ Failed to fetch transcription results. Please check your API key and run IDs.")
