Benson.py turns URLs into mp3s of the web pages' content —
take charge of your reading backlog!

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation and Usage
3. Roadmap and Future Enhancements
4. Contributing
5. License
6. Contact

About The Project

Benson accepts a list of URLs via database query or from a filename passed by command line argument and turns the web pages' content into individual audio files (currently, mp3s for portability).

I love to keep up with the latest articles and blog posts, but who has the time to relax and just catch up on reading anymore? What finally worked for me was to batch up the URLs of articles and blog posts I wanted to read and convert them to mp3 files that I listen to at 2x speed while I'm driving the car, walking the dog, or doing the dishes. Benson is the latest iteration of how I turn my reading backlog into convenient and quickly consumed audio files.

If you find Benson useful to you, by all means clone or fork it and customize to your heart's content. Pull requests are also welcome if you want to help me improve and expand the project.

As you might've guessed, I picked the name Benson after the sarcastic yet affable butler portrayed by Robert Guillaume in the 1980s sitcom Benson. It's all part of the fun tradition of naming software after butlers. (Jenkins, Alfred, Belvedere, anyone?)

(back to top)

Built With

• Trafilatura by Adrien Barbaresi for content extraction
• pyttsx3 by Natesh Bhat for text-to-speech
• ffmpeg-python by Karl Kroening for mp3 details

Thanks, y'all!

(back to top)

Getting Started

Prerequisites

• ffmpeg needs to be in your system path

Installation and Usage

1. Clone the repo.

   git clone https://github.com/timoteostewart/benson.git

2. Prepare and activate a venv (the Windows method is shown).

   python -m venv benson_env
   ./benson_env/Scripts/Activate.ps1

3. Ensure pip requirements are installed.

   pip install -r requirements.txt

4. Start turning URLs into audio files immediately. (See screenshot below.)

   python benson.py --source test-urls.txt

5. Listen to the four mp3s in the ./mp3_files folder to hear how it sounds. (Of course pyttsx3 offers plenty of ways to customize the voices.)

(back to top)

Roadmap and Future Enhancements

• If URL is not currently available or scrapable, check for snapshots on archive.is, Wayback Machine, and similar.
• Implement progress indicator with estimated time of completion (useful for very large lists of URLs)
• Populate the ID3 fields in the mp3 to the extent possible
• For domain pronunciations not in domains_pronunciations.txt, try scraping the URL of the article and try to find a human-readable string that resembles the components of the domain. For example, it would be ideal for Benson to visit "https://avanwyk.com/" and determine that "avanwyk.com" could be spoken aloud as "Andrich van Wyk dot com". Obligatory xkcd

(back to top)

Contributing

Contributions are welcome! Even small changes and refactors. Fork the repo and create a pull request. You may also open an issue with the tag "enhancement". Feel free to ⭐ the project too. Thanks!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request so I can check it out

(back to top)

License

Distributed under the MIT License. See LICENSE file for more information.

(back to top)

Contact

Tim Stewart - tim@texastim.dev

Benson project link: https://github.com/timoteostewart/benson

(back to top)