|
| 1 | +"""LlamaIndex reader that transcribes audio via Deepgram and returns Documents. |
| 2 | +
|
| 3 | +Usage: |
| 4 | + # Load audio into LlamaIndex Documents and query them |
| 5 | + python src/audio_loader.py https://dpgr.am/spacewalk.wav |
| 6 | +
|
| 7 | + # Query mode — ask a question about the audio content |
| 8 | + python src/audio_loader.py --query "What is the main topic?" https://dpgr.am/spacewalk.wav |
| 9 | +""" |
| 10 | + |
| 11 | +import os |
| 12 | +import sys |
| 13 | +from pathlib import Path |
| 14 | +from typing import List, Optional |
| 15 | + |
| 16 | +from dotenv import load_dotenv |
| 17 | + |
| 18 | +load_dotenv() |
| 19 | + |
| 20 | +# SDK v5 Python: DeepgramClient reads DEEPGRAM_API_KEY from env automatically. |
| 21 | +from deepgram import DeepgramClient |
| 22 | + |
| 23 | +# LlamaIndex core: Document is the atomic unit of data, BaseReader defines |
| 24 | +# the load_data() contract that all readers/loaders implement. |
| 25 | +from llama_index.core import VectorStoreIndex |
| 26 | +from llama_index.core.readers.base import BaseReader |
| 27 | +from llama_index.core.schema import Document |
| 28 | + |
| 29 | + |
| 30 | +class DeepgramAudioReader(BaseReader): |
| 31 | + """Transcribes audio files using Deepgram and returns LlamaIndex Documents. |
| 32 | +
|
| 33 | + Each audio URL becomes one Document whose text is the transcript. |
| 34 | + Deepgram Audio Intelligence results (summary, topics, sentiment) are |
| 35 | + attached as document metadata for filtering and enrichment in RAG pipelines. |
| 36 | + """ |
| 37 | + |
| 38 | + def __init__( |
| 39 | + self, |
| 40 | + model: str = "nova-3", |
| 41 | + smart_format: bool = True, |
| 42 | + summarize: Optional[str] = "v2", |
| 43 | + topics: bool = True, |
| 44 | + sentiment: bool = True, |
| 45 | + detect_entities: bool = True, |
| 46 | + language: str = "en", |
| 47 | + ) -> None: |
| 48 | + self.model = model |
| 49 | + self.smart_format = smart_format |
| 50 | + self.summarize = summarize |
| 51 | + self.topics = topics |
| 52 | + self.sentiment = sentiment |
| 53 | + self.detect_entities = detect_entities |
| 54 | + self.language = language |
| 55 | + self._client = DeepgramClient() |
| 56 | + |
| 57 | + def load_data(self, audio_urls: List[str]) -> List[Document]: |
| 58 | + """Transcribe each audio URL and return a list of Documents. |
| 59 | +
|
| 60 | + This follows the same pattern as llama-index-readers-assemblyai: |
| 61 | + audio in → transcription API → Document objects out. |
| 62 | + """ |
| 63 | + documents = [] |
| 64 | + for url in audio_urls: |
| 65 | + doc = self._transcribe_url(url) |
| 66 | + documents.append(doc) |
| 67 | + return documents |
| 68 | + |
| 69 | + def _transcribe_url(self, url: str) -> Document: |
| 70 | + """Transcribe a single audio URL and build a Document with metadata.""" |
| 71 | + # ← transcribe_url has Deepgram fetch the audio server-side |
| 72 | + response = self._client.listen.v1.media.transcribe_url( |
| 73 | + url=url, |
| 74 | + model=self.model, |
| 75 | + smart_format=self.smart_format, |
| 76 | + # Audio Intelligence features run on the same transcription call — |
| 77 | + # they are parameters, not separate endpoints. |
| 78 | + summarize=self.summarize, |
| 79 | + topics=self.topics, |
| 80 | + sentiment=self.sentiment, |
| 81 | + detect_entities=self.detect_entities, |
| 82 | + language=self.language, |
| 83 | + ) |
| 84 | + |
| 85 | + # response.results.channels[0].alternatives[0].transcript |
| 86 | + channel = response.results.channels[0] |
| 87 | + alt = channel.alternatives[0] |
| 88 | + transcript = alt.transcript |
| 89 | + confidence = alt.confidence |
| 90 | + words = alt.words |
| 91 | + duration = words[-1].end if words else 0.0 |
| 92 | + |
| 93 | + metadata = { |
| 94 | + "source": url, |
| 95 | + "duration_seconds": duration, |
| 96 | + "confidence": confidence, |
| 97 | + "model": self.model, |
| 98 | + "language": self.language, |
| 99 | + } |
| 100 | + |
| 101 | + # Audio Intelligence results live at response.results.{feature} |
| 102 | + summary = getattr(response.results, "summary", None) |
| 103 | + if summary and hasattr(summary, "short"): |
| 104 | + metadata["summary"] = summary.short |
| 105 | + |
| 106 | + topics_result = getattr(response.results, "topics", None) |
| 107 | + if topics_result and hasattr(topics_result, "segments"): |
| 108 | + topic_list = [] |
| 109 | + for segment in topics_result.segments: |
| 110 | + for topic in getattr(segment, "topics", []): |
| 111 | + if hasattr(topic, "topic"): |
| 112 | + topic_list.append(topic.topic) |
| 113 | + metadata["topics"] = list(dict.fromkeys(topic_list)) |
| 114 | + |
| 115 | + sentiments_result = getattr(response.results, "sentiments", None) |
| 116 | + if sentiments_result and hasattr(sentiments_result, "average"): |
| 117 | + metadata["average_sentiment"] = sentiments_result.average.sentiment |
| 118 | + |
| 119 | + entities_result = getattr(response.results, "entities", None) |
| 120 | + if entities_result and hasattr(entities_result, "segments"): |
| 121 | + entity_list = [] |
| 122 | + for segment in entities_result.segments: |
| 123 | + if hasattr(segment, "value"): |
| 124 | + entity_list.append(f"{segment.entity_type}: {segment.value}") |
| 125 | + metadata["entities"] = list(dict.fromkeys(entity_list)) |
| 126 | + |
| 127 | + return Document(text=transcript, metadata=metadata) |
| 128 | + |
| 129 | + |
| 130 | +def run_load(audio_urls: List[str]) -> None: |
| 131 | + """Load audio into Documents and print their content and metadata.""" |
| 132 | + reader = DeepgramAudioReader() |
| 133 | + documents = reader.load_data(audio_urls) |
| 134 | + |
| 135 | + for i, doc in enumerate(documents): |
| 136 | + print(f"\n{'='*60}") |
| 137 | + print(f"Document {i+1}") |
| 138 | + print(f"{'='*60}") |
| 139 | + print(f"Source: {doc.metadata.get('source', 'unknown')}") |
| 140 | + print(f"Duration: {doc.metadata.get('duration_seconds', 0):.1f}s") |
| 141 | + print(f"Confidence: {doc.metadata.get('confidence', 0):.0%}") |
| 142 | + if "summary" in doc.metadata: |
| 143 | + print(f"Summary: {doc.metadata['summary']}") |
| 144 | + if "topics" in doc.metadata: |
| 145 | + print(f"Topics: {', '.join(doc.metadata['topics'][:5])}") |
| 146 | + if "entities" in doc.metadata: |
| 147 | + print(f"Entities: {', '.join(doc.metadata['entities'][:5])}") |
| 148 | + print(f"\nTranscript preview:\n {doc.text[:300]}...") |
| 149 | + |
| 150 | + |
| 151 | +def run_query(audio_urls: List[str], question: str) -> None: |
| 152 | + """Load audio, build a VectorStoreIndex, and query it. |
| 153 | +
|
| 154 | + This demonstrates the full RAG pipeline: audio → Deepgram → Documents → |
| 155 | + embeddings → vector index → LLM-powered query. |
| 156 | + Requires OPENAI_API_KEY for LlamaIndex default LLM and embeddings. |
| 157 | + """ |
| 158 | + if not os.environ.get("OPENAI_API_KEY"): |
| 159 | + print("Error: OPENAI_API_KEY is not set.", file=sys.stderr) |
| 160 | + print("The query engine needs an LLM. Get a key at https://platform.openai.com/api-keys", file=sys.stderr) |
| 161 | + sys.exit(1) |
| 162 | + |
| 163 | + reader = DeepgramAudioReader() |
| 164 | + documents = reader.load_data(audio_urls) |
| 165 | + |
| 166 | + print(f"Loaded {len(documents)} document(s), building index...") |
| 167 | + |
| 168 | + # VectorStoreIndex embeds the documents and stores them for similarity search. |
| 169 | + # Default uses OpenAI text-embedding-ada-002 for embeddings and gpt-3.5-turbo for queries. |
| 170 | + index = VectorStoreIndex.from_documents(documents) |
| 171 | + query_engine = index.as_query_engine() |
| 172 | + |
| 173 | + response = query_engine.query(question) |
| 174 | + |
| 175 | + print(f"\n{'='*60}") |
| 176 | + print(f"Question: {question}") |
| 177 | + print(f"{'='*60}") |
| 178 | + print(f"\n{response}") |
| 179 | + |
| 180 | + |
| 181 | +def main() -> None: |
| 182 | + if len(sys.argv) < 2: |
| 183 | + print("Usage:") |
| 184 | + print(" python src/audio_loader.py <audio-url> [<audio-url> ...]") |
| 185 | + print(" python src/audio_loader.py --query 'Your question' <audio-url> [<audio-url> ...]") |
| 186 | + sys.exit(1) |
| 187 | + |
| 188 | + if sys.argv[1] == "--query": |
| 189 | + if len(sys.argv) < 4: |
| 190 | + print("Error: provide a question and at least one audio URL", file=sys.stderr) |
| 191 | + sys.exit(1) |
| 192 | + question = sys.argv[2] |
| 193 | + audio_urls = sys.argv[3:] |
| 194 | + run_query(audio_urls, question) |
| 195 | + else: |
| 196 | + audio_urls = sys.argv[1:] |
| 197 | + run_load(audio_urls) |
| 198 | + |
| 199 | + |
| 200 | +if __name__ == "__main__": |
| 201 | + main() |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments