typecaster

Dynamically generate podcasts from text. Give typecaster your text and podcast details and it will generate mp3 episode files, Speech Synthesis Markup Language text and iTunes-friendly RSS feeds.

Thanks to OpenNews for their support.

Build status License Support Python versions

Getting started

To start, install typecaster with pip:

pip install typecaster

Create a podcast:

from typecaster import Podcast

my_podcast = Podcast(title='My Podcast', link='http://mypodcast.com',
                     author='Me', description='My typecaster podcast',
                     output_path='.')

Manually add and publish an episode to the podcast:

# Load synthesizer arguments and credentials
import json
synth_args = json.load(open('params.json'))

# Add episode
episode_text = open('script.txt').read()
my_podcast.add_episode(episode_text, text_format='plain', title='Episode 1',
                       author='Me', synth_args=synth_args)

# Publish episode to RSS feed
my_podcast.publish('Episode 1')

Schedule dynamically generated episodes on your podcast:

Note: scheduling will end when the process ends. This works best when run inside an existing application. Daemonizing scheduled jobs may be a feature in the future.

from datetime import datetime

def get_episode_text():
    datestamp = datetime.utcnow().strftime('%Y%m%d')
    return open('script_' + datestamp + '.txt').read()

cron_args = { 'hour': 6 }  # At 6 am every day

my_podcast.add_scheduled_job(text_source=get_episode_text,
                             text_format='plain', cron_args=cron_args,
                             title='typecaster Episode', author='Me')

# Pause scheduled job
my_podcast.scheduled_jobs['typecaster Episode'].pause()

# Resume scheduled job
my_podcast.scheduled_jobs['typecaster Episode'].resume()

IBM API

At the moment, typecaster only supports IBM Watson’s text-to-speech API as a synthesizer. To use the API, you must get credentials from IBM and pass them as synth_args.

Right now, the API is free to use for the first million characters every month. That is about 7000 words per day. Additional characters are $0.02 per thousand. The API can accept 7 different languages and has a selection of voices for each language.

Learn more about getting credentials at IBM’s developer cloud.

Read documentation on the text-to-speech API to learn about all possible synth_args.

Examples

Podcasts built with typecaster:

API

Models

class typecaster.models.Podcast(title, link, author, description, output_path, language='en-us', subtitle=None, owner_name=None, owner_email=None, image=None, categories=[], copyright=None)

The model that holds the information for a complete podcast.

Parameters:
  • title – The title of the podcast.
  • link – The URL of the podcast.
  • author – The author of the podcast.
  • description – A description of the podcast.
  • output_path – The path to the directory that will hold the podcast’s mp3 files and RSS feed.
  • language – The language of the podcast. Defaults to ‘en-us’.
  • subtitle – The subtitle of the podcast. Defaults to None.
  • owner_name – The name of the podcast’s owner. Defaults to None.
  • owner_email – The email address of the podcast’s owner. Defaults to None.
  • image – The path to the preview image of the podcast. Defaults to None.
  • categories – A sequence of strings indicating iTunes categories. Defaults to an empty sequence.
  • copyright – The copyright of the podcast. Defaults to None.
  • episodes – A dictionary of titles mapped to Episode models for each episode in the podcast.
  • scheduled_jobs – A dictionary of titles mapped to scheduled jobs stored in the Podcast.
add_episode(text, text_format, title, author, summary=None, publish_date=None, synthesizer='watson', synth_args=None, sentence_break='. ')

Add a new episode to the podcast.

Parameters:
add_scheduled_job(text_source, cron_args, text_format, title, author, summary=None, synthesizer='watson', synth_args=None, sentence_break='. ')

Add and start a new scheduled job to dynamically generate podcasts.

Note: scheduling will end when the process ends. This works best when run inside an existing application.

Parameters:
  • text_source – A function that generates podcast text. Examples: a function that opens a file with today’s date as a filename or a function that requests a specific url and extracts the main text. Also see Episode().
  • cron_args – A dictionary of cron parameters. Keys can be: ‘year’, ‘month’, ‘day’, ‘week’, ‘day_of_week’, ‘hour’, ‘minute’ and ‘second’. Keys that are not specified will be parsed as ‘any’/’*’.
  • text_format – See Episode().
  • title – See Episode(). Since titles need to be unique, a timestamp will be appended to the title for each episode.
  • author – See Episode().
  • summary – See Episode().
  • publish_date – See Episode().
  • synthesizer – See typecaster.utils.text_to_speech().
  • synth_args – See typecaster.utils.text_to_speech().
  • sentence_break – See typecaster.utils.text_to_speech().
publish(titles)

Publish a set of episodes to the Podcast’s RSS feed.

Parameters:titles – Either a single episode title or a sequence of episode titles to publish.
unpublish(titles)

Unpublish a set of episodes to the Podcast’s RSS feed.

Parameters:titles – Either a single episode title or a sequence of episode titles to publish.
update_rss_feed()

Updates RSS feed with any changes in Podcast model.

class typecaster.models.Episode(text, text_format, title, author, link, summary=None, publish_date=None, synthesizer='watson', synth_args=None, sentence_break='. ')

The model that holds the information for a single podcast episode.

Parameters:
  • text – The text of the episode that will be synthesized to audio.
  • text_format – The format of input text. Can be ‘html’, ‘plain’ or None. None will skip converting to SSML.
  • title – The title of the episode.
  • author – The author of the episode.
  • link – The URL to the mp3 file of the episode.
  • summary – The summary of the episode. Defaults to None.
  • publish_date – The publish date of the episode. If None, set to datetime.utcnow(). Defaults to None.
  • published – An indicator of whether the episode is published or not.
  • synthesizer – See typecaster.utils.text_to_speech().
  • synth_args – See typecaster.utils.text_to_speech().
text

Get the text of the episode.

render_audio()

Synthesize audio from the episode’s text.

publish()

Mark an episode as published.

unpublish()

Mark an episode as not published.

Utils

typecaster.utils.text_to_speech(text, synthesizer, synth_args, sentence_break)

Converts given text to a pydub AudioSegment using a specified speech synthesizer. At the moment, IBM Watson’s text-to-speech API is the only available synthesizer.

Parameters:
  • text – The text that will be synthesized to audio.
  • synthesizer – The text-to-speech synthesizer to use. At the moment, ‘watson’ is the only available input.
  • synth_args – A dictionary of arguments to pass to the synthesizer. Parameters for authorization (username/password) should be passed here.
  • sentence_break – A string that identifies a sentence break or another logical break in the text. Necessary for text longer than 50 words. Defaults to ‘. ‘.
typecaster.utils.watson_request(text, synth_args)

Makes a single request to the IBM Watson text-to-speech API.

Parameters:
  • text – The text that will be synthesized to audio.
  • synth_args – A dictionary of arguments to add to the request. These should include username and password for authentication.
typecaster.utils.build_rss_feed(podcast)

Builds a podcast RSS feed and returns an xml file.

Parameters:podcast – A Podcast model to build the RSS feed from.

SSML

typecaster.ssml.convert_to_ssml(text, text_format)

Convert text to SSML based on the text’s current format. NOTE: This module is extremely limited at the moment and will be expanded.

Parameters:
  • text – The text to convert.
  • text_format – The text format of the text. Currently supports ‘plain’, ‘html’ or None for skipping SSML conversion.
typecaster.ssml.plain_to_ssml(text)

Incomplete. Returns inputted text.

typecaster.ssml.html_to_ssml(text)

Replaces specific html tags with probable SSML counterparts.

License

The MIT License (MIT)

Copyright (c) 2016 Neil Bedi

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Indices and tables