blogger 0.1.7

Command line utility for converting text to speech.

blogger

blogger is a command line utility originally created for converting articles, text, or HTML into speech. This is especially helpful for bloggers who like to provide audio options for their users.

This is a wrapper around a couple of different text to speech tools and is designed to be a simple interface for any user of the blogger CLI.

blogger is an open-source project from Buster Technologies, the creators of Buster ERP. Our company published technical and business content on the Simpler Software Blog and needed a simple tool to convert articles to audio files.

Installing

The package is available via pypi and can be install with pip or pipenv:

$ pip install -U blogger

---

The simplest examples

The blogger CLI has default options for converting text to speech with very few inputs. Here is an example taking in a string of text and outputting the audio file:

$ blogger audio "This is an awesome article" -o article.mp3

The default basic text to speech converter gets the job done but is not the best automated speech in the world. Google has built out a much more advanced cloud API for text to speech which sounds closer to real speech. For this, you can use the gtts converter and pass in an API token from Google which can be generated in the api console.

$ blogger audio \
  --converter=gtts \
  --token="$MYAPIKEY" \
  "This is another awesome article" \
  -o article.mp3

---

Options

Outside of the default configurations though, you can feed blogger some different inputs depending on what is needed.

$ blogger

Usage: blogger [OPTIONS] COMMAND [ARGS]...

  Blogger CLI

Options:
  --help  Show this message and exit.

Commands:
  audio       Generates an audio file from text, files, or urls.
  converters  Details for text to speech converters.
  providers   Details for content providers.
  voices      Details for voice options.

$ blogger audio --help

Usage: blogger audio [OPTIONS] [INLINE_TEXT]

  Generates an audio file from text, files, or urls.

  All input is assumed to be in either plain text or HTML format. Any other
  formats could have potential issues during processing.

Options:
  --text TEXT                     The text to convert to speech.
  --file TEXT                     The file path to the file containing text to
                                  convert to speech.
  --url TEXT                      Parse an article from a URL.
  -p, --provider TEXT             When parsing from a URL, the provider
                                  defines the content provider (Ex. Medium,
                                  Ghost, etc.)
  --url-title-selector TEXT       For the manual provider, this specifies the
                                  tag and class or id in the DOM that contains
                                  the title.
  --url-content-selector TEXT     For the manual provider, this specifies the
                                  tag and class or id in the DOM that contains
                                  the content.
  -t, --token TEXT                Google API token used for the gtts provider.
  -vi, --voice TEXT               The voice option.
  -vp, --pitch TEXT               The pitch of the voice on a scale of -20.0
                                  to 20.0.
  -vr, --rate TEXT                The rate of speech on a scale of 0.0 to 4.0.
  -c, --converter TEXT            The type of text to speech converter to use.
                                  Defaults to basic.
  -o, --output TEXT               The output path for the audio file. If not
                                  specified, output will go to STDOUT.
  --full-preview / --short-preview
                                  Preview the entire article before
                                  converting.
  -v, --verbose / --no-verbose    Provides more debugging information.
  -y, --yes / --no                Assumes yes to prompts.
  --help                          Show this message and exit.

Converters

There are two types of text to audio converters built into blogger.

$ blogger converters -l

basic A simple text to speech converter. (default)
gtts The Google cloud-based text to speech converter API.

Basic

The basic converter, which is used by default, converts text to speech using a simple google translate utility. As it says, it's a very basic option and outputs a decent audio file.

GTTS (Google Text To Speech)

Google provides a cloud text to speech API that works much better than their previous text to speech software. You must have an API token to use this converter.

$ blogger audio \
  --converter=gtts \
  --token="$MYAPIKEY" \
  --file=/tmp/input.txt \
  -o article.mp3

If utilizing the gtts converter, it comes with a few command line options too. The only required option is the API token:

-t, --token TEXT                Google API token used for the gtts provider.
-vi, --voice TEXT               The voice option.
-vp, --pitch TEXT               The pitch of the voice on a scale of -20.0
                                to 20.0.
-vr, --rate TEXT                The rate of speech on a scale of 0.0 to 4.0.

Read the instructions on how to generate your API token here.

Input

There are multiple ways that text can be passed into blogger. Only 1 of the following methods can be used in a single command at a time. Conflicts will result in a single input method being used and the other input being ignored.

Inline

As seen in the simple example above, you can pass text directly into the CLI:

$ blogger audio "Convert this text please" -o article.mp3

$ blogger audio --text="Convert this text please" -o article.mp3

$ blogger audio --text="Convert this text please" --output=/my_audio/article.mp3

Files

Another option is to read a file in:

$ blogger audio --file=./article.txt -o article.mp3

URL

And finally you can read articles posted online, strip out the relevant content, and produce an audio file. This is ideal for articles already written and published that need to be converted afterwards.

When reading a URL, blogger needs some help figuring out what content to be looking at. For this we use providers. A provider represents a content provider (think Medium, Ghost, Wordpress, etc.) Please see the Providers section for more details about what blog formats are supported automatically.

$ blogger audio \
  --url=https://bustererp.com/blog/whats-in-python-3-8 \
  --provider=ghost \
  -o article.mp3

$ blogger audio \
  --url=https://medium.com/@reedrehg/10-ways-to-prevent-technical-debt-33dd17075fba \
  --provider=medium \
  -o article.mp3

If a relevant provider does not exist, then you can pass selectors in to show us what exactly to look for. Generally blogger is always looking for a title and then a content body.

$ blogger audio \
    --url=https://myblog.com/myarticle \
    --url-title-selector="h1.blog-title" \
    --url-content-selector="div#blog-content" \
    -o article.mp3

Article previews

Each audio command will show you a preview of what was processed to ensure that you are pulling the right information. Use the --full-preview flag to preview the entire content, not just part of the content.

$ blogger audio --url=https://myblog.com/myarticle --provider=ghost -o article.mp3

Converting audio using the gtts converter:
  Text Preview:
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent
    turpis ante, egestas id diam sed, convallis ultrices erat.
    Praesent ut nibh non quam pellentesque finibus. Maecenas convallis,
    metus a sollicitudin porttitor, dolor leo facilisis erat,
    sed condimentum nisl quam in nunc. Quisque sed mattis ligula,
    sed finibus nunc. Proin et nisl ut leo tempor dignissim in sed
    mauris. Duis porta lacinia sapien sit amet consequat. Quisque
    eget lectus non lorem vehicula porta eu a lacus. Etiam fermentum,
    purus at malesuada tristique, lorem elit hendrerit libero,
    a molestie felis felis a nibh. Quisqu...

Processing...
Successfully outputted to /tmp/audio.mp3

Providers

Check the providers list to see the currently available blog providers supported by the system. The --provider flag will only be relevant when combined with the --url option.

$ blogger providers -l

manual Uses user provided input to determine how to parse content (default)
ghost Handles parsing content for Ghost hosted blogs (https://ghost.io)
medium Handles parsing content written on Medium (https://medium.com)

Voices

Check the voices list to see the currently available voice. This is only compatible with the gtts converter:

$ blogger voices -l

US-A United States english accent option A
US-B United States english accent option B
US-C United States english accent option C
US-D United States english accent option D
US-E United States english accent option E
US-F United States english accent option F
AU-A Australian english accent option A
AU-B Australian english accent option B
AU-C Australian english accent option C
AU-D Australian english accent option D
GB-A British english accent option A
GB-B British english accent option B
GB-C British english accent option C
GB-D British english accent option D
IN-A Indian english accent option A
IN-B Indian english accent option Bextremely
IN-C Indian english accent option C

$ blogger audio \
  --converter=gtts \
  --token="$MYAPIKEY" \
  --file=/tmp/input.txt \
  --voice="US-C" \
  --yes

Contibuting to blogger

blogger is open-source software and freely distributable under the terms of the MIT license. The source code is hosted on GitHub.

Please contribute in the form of pull requests, bug reports, or general comments in the GitHub issue tracker.

blogger was originally created by Holden Rehg, with development sponsored by Buster Technologies.

---

Buster Technologies, LLC.