audio-to-markdown
Convert audio files to Markdown format with transcription. Transforms spoken content into structured text for documentation, notes, or content creation.
Instructions
Convert an audio file to markdown, including transcription if possible
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filepath | Yes | Absolute path of the audio file to convert |
Implementation Reference
- src/server.ts:72-86 (handler)Switch case that handles the call to audio-to-markdown tool (shared with other file-to-markdown tools), validates input filepath and delegates to Markdownify.toMarkdown.case tools.PDFToMarkdownTool.name: case tools.ImageToMarkdownTool.name: case tools.AudioToMarkdownTool.name: case tools.DocxToMarkdownTool.name: case tools.XlsxToMarkdownTool.name: case tools.PptxToMarkdownTool.name: if (!validatedArgs.filepath) { throw new Error("File path is required for this tool"); } result = await Markdownify.toMarkdown({ filePath: validatedArgs.filepath, projectRoot: validatedArgs.projectRoot, uvPath: validatedArgs.uvPath || process.env.UV_PATH, }); break;
- src/Markdownify.ts:74-124 (handler)Core handler function that performs the file-to-markdown conversion for audio files (and others) by invoking the markitdown CLI tool.static async toMarkdown({ filePath, url, projectRoot = path.resolve(__dirname, ".."), uvPath = "~/.local/bin/uv", }: { filePath?: string; url?: string; projectRoot?: string; uvPath?: string; }): Promise<MarkdownResult> { try { let inputPath: string; let isTemporary = false; if (url) { const response = await fetch(url); let extension = null; if (url.endsWith(".pdf")) { extension = "pdf"; } const arrayBuffer = await response.arrayBuffer(); const content = Buffer.from(arrayBuffer); inputPath = await this.saveToTempFile(content, extension); isTemporary = true; } else if (filePath) { inputPath = filePath; } else { throw new Error("Either filePath or url must be provided"); } const text = await this._markitdown(inputPath, projectRoot, uvPath); const outputPath = await this.saveToTempFile(text); if (isTemporary) { fs.unlinkSync(inputPath); } return { path: outputPath, text }; } catch (e: unknown) { if (e instanceof Error) { throw new Error(`Error processing to Markdown: ${e.message}`); } else { throw new Error("Error processing to Markdown: Unknown error occurred"); } } }
- src/tools.ts:80-94 (schema)Input schema definition for the audio-to-markdown tool, specifying the required filepath parameter.export const AudioToMarkdownTool = ToolSchema.parse({ name: "audio-to-markdown", description: "Convert an audio file to markdown, including transcription if possible", inputSchema: { type: "object", properties: { filepath: { type: "string", description: "Absolute path of the audio file to convert", }, }, required: ["filepath"], }, });
- src/server.ts:33-37 (registration)Registers the audio-to-markdown tool (along with others from tools.ts) for the MCP listTools request.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: Object.values(tools), }; });
- src/Markdownify.ts:20-51 (helper)Helper function that executes the markitdown CLI tool via uv to convert the audio file to markdown text.private static async _markitdown( filePath: string, projectRoot: string, uvPath: string, ): Promise<string> { const venvPath = path.join(projectRoot, ".venv"); const markitdownPath = path.join( venvPath, process.platform === "win32" ? "Scripts" : "bin", `markitdown${process.platform === "win32" ? ".exe" : ""}`, ); if (!fs.existsSync(markitdownPath)) { throw new Error("markitdown executable not found"); } // Expand tilde in uvPath if present const expandedUvPath = expandHome(uvPath); // Use execFile to prevent command injection const { stdout, stderr } = await execFileAsync(expandedUvPath, [ "run", markitdownPath, filePath, ]); if (stderr) { throw new Error(`Error executing command: ${stderr}`); } return stdout; }