deck2audio

Turn your PowerPoint slides into a narrated audio lesson.

An Applied Hearing Science Lab tool from the University of Washington, designed for teachers, college instructors, and anyone who wants to turn a presentation into spoken audio. Choose a narrator, review the script, and save an MP3 that students can listen to.

You use the app in your web browser, but it runs on your own computer, not a public website. You do not need to know Git or write code. Setup does require copying a few commands into a command window; the instructions below explain how. This is not yet a double-click installer.

Before you begin

You will need:

• A Mac or Windows PC, a web browser, and permission to install software.
• A PowerPoint file ending in .pptx. If you have an older .ppt file, open it in PowerPoint and use Save As to save it as a PowerPoint Presentation (.pptx). Speaker notes are especially helpful for narration.
• Python, a free program that runs the app. Instructions are below. Python 3.11 is the version used to test this project; use it for the most predictable setup.
• Internet access for downloading/installing the software and generating audio with online voices. Kokoro and installed macOS voices work offline after setup.
• Optionally, access to an AI chat service such as ChatGPT, Claude, Copilot, or Gemini if you want help rewriting your narration. This is not required: you can use your slides and speaker notes directly.

No Microsoft PowerPoint installation is required just to process an existing .pptx file. No API key is required for the voice service. Your chosen AI chat service may have its own account requirements or charges.

Using a school-managed computer? Ask your IT staff if software installation or access to online speech services is restricted. Do not try to bypass your school's security settings.

1. Download the app (no Git required)

1. Open the deck2audio GitHub page. GitHub is simply the website where this program is distributed; you do not need a GitHub account to download a public repository.
2. Click the green Code button, then Download ZIP.
3. Find the downloaded ZIP file in your Downloads folder.
   • Mac: double-click the ZIP to unpack it.
   • Windows: right-click the ZIP, choose Extract All, then Extract. Do not run the program from inside the ZIP preview.
4. Move the unpacked folder somewhere you can keep it, such as Documents. Rename it deck2audio to make the instructions easier to follow.
5. Open that folder. You should see files such as deck2audio.py, requirements.txt, and this README. If you see only another folder, open that inner folder instead.

Keep the whole folder together, including the logo, styling files, and the hidden .streamlit folder. Do not download just one Python file.

2. Set up your computer (one time)

Choose the instructions for your computer. A command window is a place where you paste an instruction and press Enter (Windows) or Return (Mac). Copy only the text inside each command box, not the surrounding headings.

The .venv folder created below holds the app's supporting software separately from other Python programs. You do not need to open it or "activate" it.

Mac

A. Install Python

1. Go to Python downloads for macOS.
2. Choose a Python 3.11 release with a macOS 64-bit universal2 installer. It supports Intel and Apple Silicon Macs. Follow the installer instructions. If Python 3.11 is already installed, you can skip this step.
3. In Applications, open the installed Python 3.11 folder and double-click Install Certificates.command, if present. This sets up certificates used for secure internet connections.

B. Open Terminal in your app folder

1. Press Command + Space, type Terminal, and press Return.
2. Type cd followed by a space, but do not press Return yet.
3. Drag your unpacked deck2audio folder from Finder into the Terminal window. Its location will appear after cd. Press Return.

If you put the folder directly in Documents and named it deck2audio, you can instead paste:

cd "$HOME/Documents/deck2audio"

C. Install the app's supporting software

Paste these commands one at a time, pressing Return after each and waiting for it to finish:

python3.11 -m venv .venv

.venv/bin/python -m pip install -r requirements.txt

Installation may take a few minutes. Scrolling messages are normal. If a command ends with an error, see Troubleshooting before continuing.

Windows PC

A. Install Python

1. Go to Python downloads for Windows.
2. Choose a Python 3.11 release with a Windows installer appropriate for your computer (usually 64-bit). If unsure, ask your IT staff.
3. Run the installer. If offered, check Add python.exe to PATH and keep the Python launcher enabled, then choose Install Now.
4. Close any command windows you had open before installation. If Python 3.11 and its launcher are already installed, you can skip this step.

B. Open PowerShell in your app folder

1. Open the unpacked deck2audio folder in File Explorer.
2. Click the address bar at the top (where the folder location appears).
3. Type powershell and press Enter. A command window opens in that folder. Use PowerShell, not the Python interactive window.

C. Install the app's supporting software

Paste these commands one at a time, pressing Enter after each and waiting for it to finish:

py -3.11 -m venv .venv

.\.venv\Scripts\python.exe -m pip install -r requirements.txt

Installation may take a few minutes. Scrolling messages are normal. You do not need to run an activation script or change PowerShell's execution policy.

3. Start the app

In the command window, still in your deck2audio folder, run:

Mac

.venv/bin/python deck2audio.py ui

Windows PowerShell

.\.venv\Scripts\python.exe deck2audio.py ui

Leave this window open. The app will print a local web address, normally:

http://127.0.0.1:8501

Open that address in your browser. If a different port number is printed, use the printed address instead. The browser may not open automatically.

What does "local" mean? This address points to your own computer. It is not a public website, and sending the address to a colleague will not give them access to your app. They need their own installation.

To stop the app: return to the command window and press Ctrl+C (on either Mac or Windows). Closing only the browser tab does not stop it.

To use it another day: open a command window in the same app folder using the instructions above, then run the appropriate start command again. You do not need to repeat installation.

4. Make your first narrated lesson

For a first try, use a short deck with two or three slides.

1. Choose your deck. Click the upload/browse control, select your .pptx file, then click Open uploaded deck. You can inspect the extracted slide text and speaker notes.
2. Choose how to make the script.
   • Simplest option: check Skip all research and LLM drafting; use deck content directly. The app uses each slide's speaker notes, falling back to its title and body text. You can edit the result before approval.
   • AI-assisted option: leave that box unchecked. Choose your audience (professionals, graduate students, undergraduates, high school, K-12, or general audience). Add a grade, subject, or profession if helpful. Academic research and real-world-example prompts are optional.
   • Set a target duration if desired; 0 means no target. "Slides per LLM prompt" controls how many slides the AI handles at once.
   • Click Start / restart pipeline.
3. Choose a voice. Open the Voice & pacing sidebar. Choose a voice and adjust speed, pitch, and pauses. Click Preview voice (online), then press Play in the audio player. Check your volume if you cannot hear it.
4. If using AI, copy and paste. An LLM is an AI chat tool. The app gives you a prompt: instructions plus your slide content.
   • Select and copy the prompt text (Command+C on Mac; Ctrl+C on Windows).
   • Paste it into your chosen AI chat service in another browser tab.
   • Copy the complete response back into the app's response textbox.
   • Review and approve research responses, or skip those steps. For narration batches, click Accept batch and continue. Correct any flagged missing, duplicate, out-of-order, unexpected, or empty slide sections.
   • Repeat until the full script is ready. The app never calls an AI chat service automatically.
5. Review the full narration. Edit the words in the textbox. Check factual accuracy, pronunciation, audience suitability, and the closing summary. Click Approve script for audio when satisfied. If you are not ready, choose Save draft without approval. Editing an approved script requires you to approve it again.
6. Make and save the audio. Click Generate MP3 (online). Keep the app open while it works. Listen in the browser, then choose Download narrated MP3 to save it. Individual slide clips are also available. You can share the MP3 through your school's learning platform, subject to its policies.

Emergency fallback on Mac: offline system voices

If the online speech service is unavailable, open Voice & pacing and change Speech backend to macOS voices (offline fallback). The app never switches voices automatically.

• Choose System default or an installed macOS voice, then click Preview voice (offline) to audition it.
• Review and approve the script as usual, then click Generate MP3 (offline). Narrated MP3 and per-slide MP3 downloads work just like the online backend.
• Installed voices synthesize locally; narration is not sent to Microsoft's speech service. Additional voices may need a one-time download through macOS accessibility speech settings. Voice quality and available voices vary by Mac.
• Rate, slide gaps, and [pause] markers are supported. Normal rate is 175 words per minute; the percentage slider adjusts it. Pitch adjustment is not supported.
• Switching backend or voice requires regenerating audio, not reapproving an unchanged script.

The fallback requires macOS and its built-in say command. MP3 export uses the small lameenc library, included in the requirements; no FFmpeg installation is needed. For an existing installation, stop the app, run .venv/bin/python -m pip install -r requirements.txt from the app folder, and restart it. Installing dependencies requires internet; using installed local voices afterward does not. On Windows, use Edge or set up Kokoro below.

CLI users can select the same fallback:

.venv/bin/python deck2audio.py voice-test --backend macos
.venv/bin/python deck2audio.py tts path/to/project_narration --backend macos

Use say -v '?' to list installed voices, and add --macos-voice "Voice Name" to choose one. Leave --pitch at its default +0Hz.

Natural offline voices: Kokoro (Mac and Windows)

Choose Kokoro voices (offline) in Voice & pacing for local American-English speech. Three voices are offered: Heart (the default), Bella, and Michael. Kokoro runs on your CPU with ONNX Runtime; no GPU, PyTorch, API key, or FFmpeg is required. The model stays in memory between requests.

One-time setup requires internet. Stop the app first, then install the optional supporting software from your app folder:

Mac

.venv/bin/python -m pip install -r requirements-kokoro.txt

Windows PowerShell

.\.venv\Scripts\python.exe -m pip install -r requirements-kokoro.txt

Create a folder named models inside the app folder, and a folder named kokoro inside that. Download both files from the kokoro-onnx model release:

• kokoro-v1.0.onnx
• voices-v1.0.bin

Put both files directly in models/kokoro, keeping their exact filenames. Together they require about 340 MiB of disk space, in addition to the Python packages. These downloaded assets are not included in the app ZIP or Git.

Restart the app, select Kokoro voices (offline), choose a voice, and click Preview voice (offline). After approving your script, click Generate MP3 (offline). Speed, slide gaps, [pause] markers, and per-slide downloads work with Kokoro. Pitch adjustment is not supported. Switching engine or voice requires regenerating audio, not reapproving an unchanged script.

Synthesis reads only local model files and does not download anything or send narration to a service. Missing packages or models produce setup errors rather than silently switching to an online engine. Keep models/kokoro when updating or moving the app if you want to avoid downloading the assets again.

CLI examples (Mac; use the Windows Python path above on Windows):

.venv/bin/python deck2audio.py voice-test --backend kokoro --kokoro-voice af_heart
.venv/bin/python deck2audio.py tts path/to/project_narration --backend kokoro --kokoro-voice am_michael

Keep --pitch at +0Hz; Kokoro supports rates from -50% to +100%. Voice quality and pronunciation depend on the script; preview technical terms and acronyms before generating a whole presentation. The Kokoro model is Apache-2.0 licensed; the kokoro-onnx runtime is MIT licensed.

Experimental offline narration: VibeVoice and your own voice

All existing engines remain available. Two additional options are provided:

• VibeVoice voices (offline, experimental): the official Microsoft VibeVoice-Realtime model with Emma, Grace, Carter, Davis, Frank, and Mike. These are English presets; the repository does not certify each accent as American. The official Realtime release does not expose microphone-based voice cloning.
• My voice - Chatterbox (offline, experimental): a separate English voice-cloning engine that uses a recording of your voice or another speaker who has explicitly given permission.

These engines run in separate Python environments to avoid dependency conflicts with each other and Kokoro. Apple Silicon uses MPS acceleration, NVIDIA systems use CUDA when supported by their installed PyTorch build, and other systems use CPU. CPU generation can be slow. Both engines currently use natural speed and pitch; existing rate/pitch settings are retained for the other engines. Slide gaps, [pause] markers, combined MP3s, and per-slide clips are supported. Long passages are split into bounded chunks to fit the models; prosody may change at chunk boundaries.

One-time setup

Stop the app, open a command window in the app folder, and run the setup for each engine you want. These commands require internet and download public model assets from their official repositories. No API key is needed.

Mac

.venv/bin/python setup_offline_tts.py vibevoice
.venv/bin/python setup_offline_tts.py chatterbox

Windows PowerShell

.\.venv\Scripts\python.exe setup_offline_tts.py vibevoice
.\.venv\Scripts\python.exe setup_offline_tts.py chatterbox

VibeVoice installation requires Git for its pinned upstream Python package. If Git is missing, install it using your organization's approved method. Python 3.11 is the tested setup. The setup creates .venv-vibevoice and/or .venv-chatterbox and stores assets in models/vibevoice and/or models/chatterbox; it does not replace the app's .venv. Do not install these optional requirements into the app environment.

Plan for approximately 4-6 GB for VibeVoice and 5-7 GB for Chatterbox, plus installation caches and generated recordings/audio. Installing cloning is an additional download, not part of the earlier VibeVoice-only estimate. Have at least 15-20 GB free when setting up both. Actual installed size depends on platform and package versions. Models also use several GB of memory when loaded, beyond their disk sizes.

Restart the app after setup. Choose a backend in Voice & pacing, preview it, approve the narration, and generate audio as usual. First use loads a model; subsequent requests reuse a local worker until the app stops. Errors appear in the GUI; detailed model diagnostics also appear in the app's terminal. A request that exceeds ten minutes is stopped and reported as an error.

Record your own narrator

1. Select My voice - Chatterbox (offline, experimental).
2. Allow microphone access in your browser, then use Record your voice. Microphone access works on localhost or a trusted HTTPS origin. Alternatively, upload an uncompressed 16-bit mono or stereo WAV.
3. Record 5-30 seconds of clean, single-speaker speech without music. Supported recording rates are 16-48 kHz; maximum file size is 10 MB. Chatterbox conditions on roughly the first 6-10 seconds, so put clean speech at the beginning. Silent, truncated, and unsupported WAV files are rejected; this validation is not speech recognition or identity verification.
4. Confirm that it is your voice or that the speaker explicitly permitted cloning. Click Save voice reference. If both inputs are present, the microphone recording takes precedence.
5. Preview the cloned narrator, approve the script, and generate your MP3.

Recordings are saved only when you explicitly click Save, inside the active project's voices folder. They are named by content hash, so saving a different reference changes the audio settings and requires regeneration. References persist when resuming a project. Use Delete selected voice reference to remove a saved reference; clear the microphone/upload widgets to discard their unsaved inputs. Deletion does not remove old MP3s, downloaded copies, or backups. Recordings are personal data: protect the project folder and backups.

Only clone your own voice or a voice you have explicit permission to use. Clearly disclose that shared narration is AI-generated; do not present it as a genuine recording or use it to impersonate someone. Similarity, accent, and pronunciation are not guaranteed.

Offline operation and costs

After setup, these workers load local files with Hugging Face/Transformers offline mode enabled, telemetry disabled, and outbound Python socket connections and DNS resolution blocked. Missing assets produce errors, not online fallbacks. Neither narration nor microphone references are sent to a speech service. The existing Edge option remains online only when explicitly selected.

There are no required subscriptions, API charges, per-minute fees, or usage royalties for local synthesis. Hardware, electricity, disk space, initial downloads, and optional software updates remain ordinary local costs. The VibeVoice code, VibeVoice model, Chatterbox code, and Chatterbox model are MIT licensed; their dependency licenses also apply. Chatterbox includes its upstream audio watermarking. VibeVoice is research-oriented software; test pronunciation, fidelity to the script, and technical terminology before sharing a lesson.

CLI examples:

.venv/bin/python deck2audio.py voice-test --backend vibevoice --vibevoice-voice Grace
.venv/bin/python deck2audio.py tts path/to/project_narration --backend vibevoice --vibevoice-voice Emma
.venv/bin/python deck2audio.py voice-test --backend chatterbox --voice-reference /path/to/my-consented-voice.wav

CLI users are responsible for obtaining permission for the reference they supply. Keep --rate at +0% and --pitch at +0Hz for these two engines.

What the AI-assisted script aims to do

The prompts request a personable one-person podcast style with natural "you" and "I", gentle humor, and audience-relatable examples without repetitive stories or invented personal experiences. The last slide should end with a summary of the entire presentation, even if your deck has no summary slide.

The AI is asked to fact-check slide text and notes, avoid over-claiming, and clarify the original message rather than critique the deck. Study references should describe a finding and introduce the team/lead researcher, institution, and publication year using verified details, rather than name-drop researchers.

AI instructions are not a guarantee of accuracy. Check important claims yourself. Direct deck-content mode does not fact-check, add examples or humor, or write a new closing summary. Audience, duration, and batching settings do not rewrite content in that mode.

Your files, privacy, and internet access

• Your original PowerPoint is not edited. Browser uploads and saved work go into the app's ui_projects folder. Use Resume a saved browser project to continue later. Keep that folder when backing up or updating the app.
• Save before leaving. Accepted responses and saved drafts are stored on disk; unsaved response textbox edits may be lost when you close the browser. Restarting a pipeline clears the active script approval and research selection.
• Treat saved work as private. People with access to this app folder can access its projects. It is not designed as a shared, authenticated service.
• Internet is required for initial installation and online voice previews and MP3 generation. The online speech service receives the text it will speak. The macOS fallback uses installed voices locally and works offline after setup. Kokoro also works offline after installing its packages and model files. VibeVoice and Chatterbox work offline after their separate setup; microphone recordings are processed locally by Chatterbox. Extraction, direct script preparation, and review work offline after setup.
• AI chat is your choice. Prompts contain slide text and speaker notes. Pasting them into an AI service shares that content with that service.
• Follow school privacy rules. Do not send student information, confidential material, or other restricted content to AI or speech services unless you have permission. Microsoft's online speech service is accessed through edge-tts; the app does not require an API key.
• The launcher listens only on your own computer and disables Streamlit usage telemetry. Local styling and the bundled lab logo need no external downloads while the app is running.

Troubleshooting

What you see	What to do
python3.11 or py is not found	Install Python 3.11 using the instructions above, then close and reopen the command window. On Windows, confirm the Python launcher was installed.
"Can't open file", "No such file", or requirements.txt not found	You are probably in the wrong folder. Open the unpacked folder containing deck2audio.py and requirements.txt, then open your command window there.
.venv or its Python executable is missing	Complete the one-time setup commands first. If you moved the app folder after setup, recreate .venv and reinstall the supporting software in its new location.
No module named streamlit or another missing module	Repeat the supporting-software installation command for your computer. Start the app with the .venv command shown above, not a different Python installation.
The browser cannot connect	Make sure the command window is still running without an error. Use the exact local address printed there. The address works only on the computer running the app.
"Port 8501 is already in use"	Another copy may be running. Use its browser page, or stop the old copy with Ctrl+C before starting again.
Installation or audio generation has a network/certificate error	Check your internet connection and school network restrictions. On Mac, run Python's Install Certificates.command if available. Ask IT for help rather than disabling certificate checks.
Voice preview has a player but no sound	Press Play, check computer volume and output device, and ensure the browser tab is not muted.
Voice preview or MP3 generation shows an error	Read the displayed message. Check internet access; try a built-in voice instead of a custom voice ID. The online service may be temporarily unavailable.
Online speech returns WSServerHandshakeError: 403	The online service rejected synthesis. Select Kokoro voices (offline) after its one-time setup, or macOS voices (offline fallback) on Mac. Preview a local voice and generate again. The app does not switch narrators automatically.
The local MP3 encoder is missing	Stop the app, reinstall the updated requirements with your app's .venv Python, and restart it.
Kokoro is not installed, or its model files are missing	Follow Kokoro setup, including both model downloads, then restart the app.
VibeVoice or Chatterbox is not set up, or its worker reports a missing asset	Run the matching setup_offline_tts.py command above using the app's Python, then restart. Inspect the app terminal for detailed errors.
No microphone recording control works	Open the app on localhost, allow browser microphone access, and check the selected input device. You can upload a consented WAV instead.
The voice recording is rejected	Use 5-30 seconds of clear speech in an uncompressed 16-bit mono/stereo WAV at 16-48 kHz, at most 10 MB.
A slide has no usable text or notes	Add speaker notes or text in PowerPoint, save, and upload the revised deck. Images alone are not converted into narration.
Audio generation is disabled	Review and approve the full script. Changes to approved text require reapproval.
A school computer blocks installation	Ask your IT staff for assistance. Do not bypass security policies.

If you need more help, ask your IT staff or report the problem through GitHub Issues (a GitHub account is needed to post). Include your operating system, the step you were following, and the exact error message. Do not attach private slides, student information, or confidential script text.

Updating to a newer version

1. Save your draft/accepted responses, download any audio you want to keep, and stop the app with Ctrl+C.
2. Back up your current app folder, especially ui_projects.
3. Download and unpack a new ZIP from GitHub into a new folder.
4. Run the one-time setup commands in that new folder. Do not copy the old .venv folder; it depends on where it was created.
5. To retain browser projects, copy your backed-up ui_projects folder into the new app folder. Leave your backup untouched until you confirm they resume.
6. Start the new version and open the printed local address.

Optional: command-line use (for experienced users)

Most users can ignore this section. The original command-line interface (CLI) remains available. These examples are for Mac; on Windows, replace .venv/bin/python with .\.venv\Scripts\python.exe and use Windows file paths.

# Full workflow; re-run to resume
.venv/bin/python deck2audio.py run ~/Desktop/MyTalk.pptx --audience "MBA students" --minutes 15

# Use deck content without AI drafting
.venv/bin/python deck2audio.py run ~/Desktop/MyTalk.pptx --skip-all

# Try a narrator
.venv/bin/python deck2audio.py voice-test --voice en-US-EmmaMultilingualNeural --rate -5%

Stage	Command	What happens
Extract	extract deck.pptx	Saves slide titles, body text, tables, and notes as slides.json and slides.md.
Research	research deck.pptx --audience "high school students"	Creates academic and example prompts for manual AI interaction and approval.
Script	script deck.pptx	Drafts/approves ## Slide N narration sections, with batching and final review. Supports --skip-all.
Audio	tts deck.pptx	Generates a combined MP3 and per-slide clips from script.md.

CLI output goes into <deck>_narration next to the deck. You can also pass this project folder to later stages. The browser's Open an existing CLI project control can open that folder.

Voice options include --voice, --rate (such as -5%), --pitch (such as +2Hz), --slide-gap 1.2, --pause 0.8, and -o out.mp3. [pause] markers in scripts create silence. The browser and CLI share narration prompts; later batches include all earlier accepted narration to help avoid repeated examples, and the final batch includes full-deck context for the closing summary.

For contributors: tests

.venv/bin/python -m unittest -q test_deck2audio test_browser_workflow

Tests cover CLI compatibility, shared prompts, saved browser workflows, validation/approval, branding, and Streamlit controls. TTS is mocked; tests do not send decks or narration to an online service.

Lab branding and license

The interface's navy/blue background, cream text, gold accents, and rounded controls are inspired by the lab's Hearing-Test interface. The bundled lab logo comes from that repository's images/logo.png. Restart the UI server after changing theme configuration.

Program license: MIT.