Podcastfy: three surfaces, one client module, and an ffmpeg prerequisite with three answers
An Open Source Python alternative to NotebookLM's podcast feature: Transforming Multimodal Content into Captivating Multilingual Audio Conversations with GenAI
At a glance
- What is it?
- Podcastfy turns websites, PDFs, images, YouTube videos and user supplied topics into multi-lingual audio conversations through GenAI, offered as a Python package, a command line module and a beta API. The seams worth checking are the ffmpeg prerequisite, the key wiring in the compose file, and a version string that runs ahead of the newest tag.
- Who is it for?
- Podcastfy suits teams that already hold model keys and want podcast generation written as code rather than filled into a web form. It does not suit anyone who needs a settled release line or a documented API beyond urls, since the FastAPI path is labelled beta, the newest tag is v0.4.0 and the build metadata says 0.4.3.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Activity is slowing. The repository last received commits 6 months ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- souzatharsis/podcastfy6,811 ★ · +256
| Repository | 2026-09-15 | 2026-11-15 |
|---|---|---|
| souzatharsis/podcastfy | 6.6k | 6.8k |
256 Stars in the last 61 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Three surfaces reach the same client module
Podcastfy is an open source Python package that transforms multi-modal content, text and images, into multi-lingual audio conversations using GenAI. Input content includes websites, PDFs, images, YouTube videos, as well as user provided topics. Three surfaces sit on top of it. The Python entry point is a single function:
from podcastfy.client import generate_podcast
audio_file = generate_podcast(urls=["<url1>", "<url2>"])The command line calls that module as a script:
python -m podcastfy.client --url <url1> --url <url2>The third surface is an HTTP API, and the project labels it Beta for urls. That phrase is the entire scope claim: the documented example passes urls, and nothing in the quickstart shows uploaded files or a batch of them. The API is containerized through a separate Dockerfile_api, and the example it points at is a fetch_audio(request_data, ENDPOINT, BASE_URL) call. For a reader, scripts and notebooks are the documented path and anything wider on the API side is unstated. The dependency on typer ^0.12.5 is where the command line parser comes from, and usage/cli.md holds the full flag reference, since the quickstart shows only --url.
The image installs the published wheel, not your checkout
The Dockerfile builds on ubuntu:24.04, sets DEBIAN_FRONTEND=noninteractive so apt stops asking questions, and installs python3-full, python3-pip and ffmpeg through apt-get. It creates a virtual environment at /opt/venv, puts /opt/venv/bin on the PATH, upgrades pip, and then installs one package:
RUN pip install --no-cache-dir podcastfyThat single line decides what you are testing. The image pulls podcastfy from PyPI, so the container runs whatever the index serves, not the source sitting next to the Dockerfile. The build even records what it received, echoing the Ubuntu release, the ffmpeg version, the Python version, the pip version and the whole pip list during the build. The entrypoint is CMD ["python3"], an interactive interpreter rather than a server, so something has to be launched inside the container. The compose file has an answer for local work: the podcastfy-dev service mounts the working tree at /app, mounts /opt/venv from the host, and sets PYTHONPATH=/app, which puts your files ahead of the installed package. The plain podcastfy service does none of that.
Compose passes two keys and health checks the import
The compose file is version 3.8 and defines three services. podcastfy builds from Dockerfile and maps port 8000 to 8000. podcastfy-dev builds from Dockerfile.dev and maps 8001 to 8000. The test service also builds from Dockerfile.dev with the same volumes and runs:
pytest -n auto --dist loadfileTwo environment variables are declared for every service, GEMINI_API_KEY and OPENAI_API_KEY. The health check on the podcastfy and podcastfy-dev services is the same:
healthcheck:
test: ["CMD", "python3", "-c", "import podcastfy"]
interval: 30s
timeout: 10s
retries: 3An import is all that verifies, so a container can report healthy while every model call behind it fails on a missing key. The narrow key list deserves the same attention as the health check. The dependency set includes elevenlabs, edge-tts, google-cloud-texttospeech, google-genai, langchain-google-vertexai and litellm, so the package can reach several language model and text to speech providers, but compose wires only the Gemini and OpenAI ones. Anyone running ElevenLabs voices through compose has to add the needed variables by hand.
ffmpeg arrives as a pip package, an apt package and a prerequisite
Installing ffmpeg is the step with three different answers. The quickstart lists it under prerequisites as pip install ffmpeg, for audio processing. The dependency list in pyproject.toml carries ffmpeg = "^1.4" next to pydub = "^0.25.1", which handles the audio assembly. The container image ignores both and installs the real binary with apt-get inside the ubuntu:24.04 base. A laptop install that follows the quickstart and a container that follows the Dockerfile are not guaranteed to hold the same thing. Python version is the other hard edge: the quickstart says 3.11 or higher, pyproject requires ^3.11, and every pin in requirements.txt is marked for python_version >= "3.11" and < "4.0". numpy is held between 1 and 2, so a shared environment carrying a newer numpy will not resolve cleanly.
pyproject says 0.4.3 while the newest tag is from 2024
The version fields disagree in a way that matters when you pin. pyproject.toml declares version = "0.4.3" under tool.poetry, and requirements.txt resolves a full tree against it. The release list stops at v0.4.0, published on 2024-11-16, preceded by v0.3.6 on 2024-11-13 and v0.3.2 on 2024-11-07. So the version in the build metadata sits three patch releases above the newest tag in that list, and there is no tag to compare a 0.4.3 install against. The default branch is main, the repository is not archived, and the last push to it was on 2026-05-04, so the tree moves long after the release history does. CHANGELOG.md at the root is where changes are recorded, and tests/ holds the suite the compose test service runs with xdist. If a behaviour matters to you, install the wheel version you tested rather than the branch tip.
Shorts and longform are chosen before the audio exists
Podcastfy produces two product shapes. The feature list names shorts at 2 to 5 minutes and longform at 30 minutes or more, and the published sample table shows how the choice is requested: an audio link marked longform=True beside a 5 hour interview with Dario Amodei, and another longform=True entry for Benjamin Franklin's Autobiography. Both are text sources, so the length setting is not derived from the input duration. That is a workflow consequence: you choose between a short clip and a half hour programme before generation starts, and a five hour source does not become five hours of audio. The transcript side names 100+ LLM models including OpenAI and Anthropic, plus a separate path for local models, 156+ HuggingFace models, offered for increased privacy and control. Text to speech is a different set again: OpenAI, Google, ElevenLabs and Microsoft Edge, with edge-tts = "^7.2.3" in the dependency list for the Edge option. Published multi-language examples are French from an agroclimate website and Brazilian Portuguese from a news article about election polls in São Paulo.
Two YAML files ride along inside the wheel
Configuration ships as data inside the package, and pyproject.toml states exactly what goes into the distribution:
include = [
"podcastfy/config.yaml",
"podcastfy/conversation_config.yaml"
]Those two files are the knobs behind the customization page. One holds the general configuration and the other configures the conversation itself, where the documented controls are format, style and voices. Everything beyond that sits behind usage/config.md, the same page that covers API keys. Editing either file in a checkout changes a run from that checkout only, because an installed copy carries its own. The dependency list gives a hint about how values arrive: pyyaml = "^6.0.2" reads the YAML and python-dotenv = "^1.0.1" is present for environment values, while compose passes GEMINI_API_KEY and OPENAI_API_KEY as plain variables. setuptools, wheel and cython are declared alongside, and the build backend is poetry-core.
Three Dockerfiles, a Makefile and a notebook in the root
The repository root shows how the project is built and run without much prose. There are three container definitions: Dockerfile for the PyPI install, Dockerfile.dev for a mounted working tree, and Dockerfile_api for the HTTP service. Next to them sit Makefile, make.sh and procfile. podcastfy.ipynb at the root is the quickstart notebook, and usage/examples.ipynb produced the published audio samples. docs/ plus .readthedocs.yaml feed the reference manual hosted on readthedocs, built by build_docs.py, which the package exposes as a console script:
[tool.poetry.scripts]
build_docs = "build_docs:main"The documentation stack sits in the runtime dependency list rather than in an extras group: sphinx-rtd-theme, sphinx-autodoc-typehints, nbsphinx and pandoc are all declared under tool.poetry.dependencies, so every pip install resolves them. The tool.poetry.group.dev section adds black ^24.8.0 and mypy ^1.11.2, along with sphinx >= 8.0.2 and ipykernel. The tree also carries GUIDELINES.md, CODE_OF_CONDUCT.md, PRIVACY_POLICY.md, NOTICE, TESTIMONIALS.md and a data/ directory, and pytest with pytest-xdist are runtime dependencies too, which is what lets the compose test service run the suite against an installed environment.
Editorial conclusion
Podcastfy suits teams that already hold model keys and want podcast generation written as code rather than filled into a web form. It does not suit anyone who needs a settled release line or a documented API beyond urls, since the FastAPI path is labelled beta, the newest tag is v0.4.0 and the build metadata says 0.4.3. Before you adopt it, check which ffmpeg your install actually put on PATH, add the key variables your chosen text to speech provider needs, and read CHANGELOG.md for anything that changed after the tag you are pinning.
Frequently asked questions
What does Podcastfy need before it will run?
Python 3.11 or higher, ffmpeg for audio processing, and your own API keys. Installation from PyPI is pip install podcastfy, then the keys are set up through the project's configuration page. The pyproject build requires ^3.11 and the pins in requirements.txt target 3.11 up to 4.0.
Which inputs does Podcastfy accept?
Websites, PDFs, images, YouTube videos and user provided topics. The dependency list backs those up with PyMuPDF for PDFs, youtube-transcript-api, beautifulsoup4 and pydub for audio, so the accepted formats are tied to specific libraries rather than one generic importer.
Can Podcastfy generate a transcript without a hosted model?
Yes. The project offers local LLM runs with 156+ HuggingFace models, described as a path for increased privacy and control, alongside transcript generation with 100+ LLM models from providers such as OpenAI and Anthropic.
How long is the audio Podcastfy produces?
Shorts run 2 to 5 minutes and longform runs 30 minutes or more, and the choice is requested with longform=True in the examples. The published longform samples come from a 5 hour interview and from a book, so the length is set independently of the source duration.
Is there an HTTP API, and how complete is it?
There is one, containerized through Dockerfile_api, and the project labels it Beta for urls. The documented call is fetch_audio(request_data, ENDPOINT, BASE_URL).
Which Podcastfy version should I pin?
pyproject.toml declares version 0.4.3, while the newest release in the tag list is v0.4.0 published on 2024-11-16. The repository is not archived and the last push to main was on 2026-05-04, so the branch and the releases move at different speeds. CHANGELOG.md records what changed.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/souzatharsis-podcastfy)Star history chart for your README
[](https://hysenlabs.com/projects/souzatharsis-podcastfy)Was this useful?