PDF2MP3 — Listen to text-based PDFs
PDF2MP3 is a Python command-line tool that turns the readable text in a PDF into
a single MP3 file. It extracts and cleans text locally, splits it into chunks,
requests speech from Microsoft's online voice service through edge-tts, and
joins the audio using pydub and FFmpeg.
Use it to listen to text-based documents in English or Brazilian Portuguese. Reading order and pronunciation depend on the PDF's extracted text and the voice service; complex layouts may need preparation before conversion.
Privacy: the default voice engine sends extracted text chunks to an external Microsoft service for speech synthesis. The PDF itself is read locally by this tool, but the default conversion requires external processing. Progress does not include document snippets. Only use documents whose contents you are permitted and comfortable to send to the selected provider.
Version 2 introduces a redesigned CLI. The conversion and check examples
below require version 2. Version 1.0.0 uses pdf2mp3 sample.pdf, without
subcommands or JSON. See the
CLI contract and quality gates.
Requirements
- Python 3.10+. The configured test matrix covers 3.10–3.14. Version 2 includes a conditional audioop compatibility dependency for Python 3.13+. See support details, including version 1.0.0's limits.
- FFmpeg, including
ffprobe, must be available on yourPATHfor audio decoding and MP3 export. Installing the Python package does not install FFmpeg. - An internet connection is required for the default Edge voice service. Availability of the service and individual voices can change.
- A PDF containing extractable text. Image-only scans require OCR beforehand.
Install
1. Install FFmpeg
macOS with Homebrew:
brew install ffmpeg
Debian/Ubuntu:
sudo apt-get update
sudo apt-get install ffmpeg
Windows with winget:
winget install --id=Gyan.FFmpeg -e
Open a new terminal if the installer updates your PATH, then check:
ffmpeg -version
ffprobe -version
2. Create a Python 3.12 environment
macOS/Linux:
python3.12 -m venv .venv
source .venv/bin/activate
Windows PowerShell:
py -3.12 -m venv .venv
.venv\Scripts\Activate.ps1
3. Install version 2
With the environment activated:
python -m pip install --upgrade pip
python -m pip install pdf2mp3==2.0.1
pdf2mp3 --version
pdf2mp3 --help
python -m pdf2mp3 --help
Both commands invoke the same CLI. The console command is installed through
pyproject.toml; module execution is provided by pdf2mp3/__main__.py.
Confirm that --version reports 2.0.1 before using these examples. Upgrading
from version 1 requires the new convert/check syntax. Follow the
CLI migration contract when updating existing scripts.
If pdf2mp3 is not found, activate the environment where you installed it or use
python -m pdf2mp3 with that environment's Python interpreter.
Convert a PDF
Start with a short document containing non-sensitive sample text. In the activated environment, convert it using the Portuguese defaults:
pdf2mp3 convert "sample.pdf"
On success, this writes sample.mp3 next to the input, using pt-BR-ThalitaNeural.
Choose English explicitly; the tool does not translate the document:
python -m pdf2mp3 convert "sample.pdf" --lang en
Choose an output location:
pdf2mp3 convert "sample.pdf" --output "audio/sample.mp3"
Adjust speaking rate, volume or chunk length:
pdf2mp3 convert "sample.pdf" --rate=+5% --volume=+0% --max-chars 1200
Negative percentages accept either --rate -5% or --rate=-5%.
An existing destination is refused unless you add --overwrite; there are no
interactive prompts. The input PDF and an existing destination are preserved
on failed export. Input/output collisions are always rejected. Choose distinct
output names when trying several examples on the same sample.
Options for the default Edge workflow
| Argument | Purpose | Default |
|---|---|---|
INPUT after convert |
Path to a PDF containing readable text | Required |
-o, --output |
Output MP3 path | Input path with .mp3 extension |
-l, --lang |
en or pt-br |
pt-br |
--voice |
Explicit Edge voice name | en-US-AriaNeural for English; pt-BR-ThalitaNeural for Portuguese |
--rate |
Speaking rate adjustment | +0% |
--volume |
Speaking volume adjustment | +0% |
--max-chars |
Chunk size before TTS sanitization; use a positive integer | 1600 |
--overwrite |
Explicitly allow destination replacement | Off |
--quiet |
Suppress progress, keep result and errors | Off |
--json |
One structured result on stdout, also on errors | Off |
-h, --help |
Display help (convert --help for provider options) |
— |
Version 2 also provides optional gTTS, OpenAI, pyttsx3 and macOS say adapters. See
provider installation and requirements before using them.
Remote adapters send text to their respective services; OpenAI requires an API
key and may incur charges. Local adapters depend on installed system voices.
Automated adapter tests use synthetic responses and do not certify live voice availability.
The OpenAI adapter now uses Realtime with gpt-realtime-2.1-mini, receives PCM
and encodes MP3 locally. It rejects incomplete responses or changed narration
transcripts. See OpenAI setup, limitations and migration;
this integration has offline evidence, not live API validation.
The gTTS extra retains a Click version constraint and a
historical, now withdrawn security advisory.
Current audits no longer report it; no dependency override or security exemption is used.
Use convert --help to inspect provider options. --voice selects Edge,
OpenAI or local voices; --model applies only to OpenAI. gTTS uses --lang.
Irrelevant provider options are rejected before processing. See
the CLI contract for stable exit codes and migration details.
Check before converting
pdf2mp3 check
pdf2mp3 check "sample.pdf" --engine edge --json
check verifies local requirements and optionally extracts/prepares a PDF. It
does not synthesize speech, contact voice services or write files. It reports
configuration, text/chunk counts and whether conversion would send text
externally. Passing this check does not establish remote voice availability or
valid credentials. --json works before or after either subcommand; progress
and diagnostics go to stderr. See the CLI guide.
Limits and troubleshooting
- Scanned PDFs: PDF2MP3 does not perform OCR. Run a separate OCR tool first to add a text layer, then check that the text extracts correctly.
- Document structure: columns, tables, headers and footers may produce unexpected reading order. Text cleanup is heuristic; it does not reconstruct the visual layout or guarantee a faithful audiobook.
- Remote speech: the Edge path retries failed speech requests, but network problems, unavailable voices or service changes can still stop conversion. Local installation/help checks do not verify live speech availability.
- Long documents: audio is assembled in memory, so large documents can use substantial memory and take time to process. Try a short sample first.
- Audio errors: confirm
ffmpegandffprobeare onPATH. Foraudioop/pyaudioopimport errors, use a fresh Python 3.12 environment. - PDF parser security: version 2.0 requires
pdfminer.six>=20251230, raising the Python minimum to 3.10. Keep dependencies updated; the quality gate audits the resolved versions. Parsing a PDF is not a sandbox for untrusted files.
Install from source
To install the release source, create and activate a separate Python 3.12 environment as above, then:
git clone --branch v2.0.1 https://github.com/byraphaelmedeiros/pdf2mp3.git
cd pdf2mp3
python -m pip install .
pdf2mp3 --help
python -m pdf2mp3 --help
python -m pip install . installs the package and its declared base dependencies.
The repository's requirement files now delegate to that same package metadata;
requirements-dev.txt also installs the pinned QA tools.
For contributor setup, see CONTRIBUTING.md.
Try the synthetic demo
After installing the development requirements and activating .venv-dev as
described in CONTRIBUTING, generate a small text-based PDF:
python scripts/create_demo_pdf.py
pdf2mp3 check local/inputs/demo.pdf --json
pdf2mp3 convert local/inputs/demo.pdf --output local/outputs/demo-edge.mp3
The first command creates local/inputs/demo.pdf with synthetic Brazilian Portuguese text;
it refuses to replace an existing file. The conversion sends only this sample
text to the external Edge service. For an English sample, macOS offline speech
and Windows validation steps, see the local demo guide.
Generated demo PDFs and MP3s stay local and are ignored by Git.
Project information
- Documentation
- Python API reference
- Changelog
- Contributing and Code of Conduct
- Security policy: report vulnerabilities privately to pdf2mp3@byraphaelmedeiros.com.
- MIT license
Maintained by Raphael Medeiros.
Metadata
Release files for pdf2mp3 2.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pdf2mp3-2.0.1.tar.gz | 86.4 kB | With provenance | Details for pdf2mp3-2.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pdf2mp3-2.0.1-py3-none-any.whl | Python 3 | none | any | Details for pdf2mp3-2.0.1-py3-none-any.whl |
Total release size: 109.6 kB
Release files / pdf2mp3-2.0.1.tar.gz
| Download URL | pdf2mp3-2.0.1.tar.gz |
|---|---|
| Size | 86.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0230f0fac3af5913764197e7fed2954ccc9ed1e88f7e811f3dbf4b48ee85f5de
|
|
BLAKE2b-256 checksum How to use checksums |
29822f3e2df185ccba79320ef0688686419ecf78fcbc60ede7839241649b4310
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.
Transparency logRelease files / pdf2mp3-2.0.1-py3-none-any.whl
| Download URL | pdf2mp3-2.0.1-py3-none-any.whl |
|---|---|
| Size | 23.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4ba09ad857eb6b95bf5df33c76ae1cc6c875502b0a4dd0ee4ba75a9a579f63a1
|
|
BLAKE2b-256 checksum How to use checksums |
06b227abceec6d55240abc6ad9dbd60ec86e264463834387caa80c2c4905b6c0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.
Transparency logSecurity for pdf2mp3 2.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pdf2mp3-2.0.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.