tinycast

README

tinycast

Automatically compress podcasts to tiny file sizes for bandwidth constrained connections like cellular or satellite.

Use Case

Sometimes I'm in locations where Internet connectivity is weak or expensive, but I'd still like to listen to the latest episode of my favorite podcasts. Podcasts can be pretty large files to download (50-100 MiB), but if you are willing to reduce the quality they can be much smaller to download (2-10 MiB).

Instead of downloading the episode to my server in a fast connection, manually compressing the file and copying it over, I wanted a way to download the files in a regular podcast app, right on my phone.

Conversion

This service takes a podcast feed and changes the links to podcasts downloads to point to the service. When a podcast file is requested, the service transcodes the audio file on the fly (without storing it locally first) and streams the much smaller file to the client.

Screenshots

Deployment

Docker

An example Dockerfile.

docker run -d \
  --name=tinycast \
  -e PORT=8082 \
  -e BASE_URL="http://example.com:8082/" \
  -p 8082:8082 \
  --restart unless-stopped \
  sholiday/tinycast

Docker Compose

An example docker-compose.yml.

---
version: "3"
services:
  tinycast:
    image: sholiday/tinycast:latest
    restart: unless-stopped
    environment:
      - BASE_URL=https://tinycast.example.com/
      - API_KEY=AUniqueStringForTheDeployment

Documentation

Index

• Variables
• func ParseChannelMode(in string) (mp3.ChannelMode, error)
• type App
  • func NewApp(baseURL url.URL, apiKey string) *App
  • func (a *App) Convert(c *gin.Context)
  • func (a *App) Feed(c *gin.Context)
  • func (a *App) Home(c *gin.Context)
• type BitRate
  • func ParseBitRate(in string) (BitRate, error)
  • func (br BitRate) ToString() string
• type BitRateMode
  • func ParseBitRateMode(in string) (BitRateMode, error)
  • func (brm BitRateMode) ToMp3BitRateMode(br BitRate) mp3.BitRateMode
• type ConversionConfig
  • func BindConversionConfig(c *gin.Context) (ConversionConfig, error)
  • func (cfg ConversionConfig) ToQueryValues() url.Values
• type Page
• type Pagination
  • func (p Pagination) CurrentPage() int
  • func (p Pagination) FirstItem() int
  • func (p Pagination) LastPage() int
  • func (p Pagination) NextPage() int
  • func (p Pagination) NumPages() int
  • func (p Pagination) Pages() []Page
  • func (p Pagination) PreviousPage() int

Variables

var BitRateModes = []BitRateMode{
	"ABR",
	"CBR",
	"VBR",
}

BitRateModes are the modes accepted by the encoder.

var BitRates = []BitRate{
	16,
	32,
	64,
}

BitRates supported by the MP3 encoder.

var ChannelModes = []mp3.ChannelMode{
	mp3.Mono,
	mp3.Stereo,
	mp3.JointStereo,
}

ChannelModes supported by the MP3 encoder.

var Templates embed.FS

Templates holds the HTML/JavaScript/CSS/Images for the web app.

Functions

func ParseChannelMode

func ParseChannelMode(in string) (mp3.ChannelMode, error)

ParseChannelMode translates from the string version of a ChannelMode.

Types

type App

type App struct {
	// contains filtered or unexported fields
}

App is the core tinycast web app with handlers and state.

func NewApp

func NewApp(baseURL url.URL, apiKey string) *App

NewApp returns a new App based on configuration.

func (*App) Convert

func (a *App) Convert(c *gin.Context)

Convert is a handler which re-encodes an audio stream to MP3 on the fly.

func (*App) Feed

func (a *App) Feed(c *gin.Context)

Feed is a handler which replaces all download entries in a podcast feed with a URL handled by the Conversion handler.

func (*App) Home

func (a *App) Home(c *gin.Context)

Home is a handler which allows users to search for podcasts to subscribe to.

type BitRate

type BitRate int

BitRate used to encode an audio file.

func ParseBitRate

func ParseBitRate(in string) (BitRate, error)

ParseBitRate converts a string version of BitRate.

func (BitRate) ToString

func (br BitRate) ToString() string

ToString returns a string version of the BitRate.

type BitRateMode

type BitRateMode string

BitRateMode describes how the MP3 encoder should apply bit rate limits.

func ParseBitRateMode

func ParseBitRateMode(in string) (BitRateMode, error)

ParseBitRateMode returns a BitRateMode if it matches the given string or an error.

func (BitRateMode) ToMp3BitRateMode

func (brm BitRateMode) ToMp3BitRateMode(br BitRate) mp3.BitRateMode

ToMp3BitRateMode converts a BitRateMode and BitRate to an mp3.BitRateMode.

type ConversionConfig

type ConversionConfig struct {
	URL         string
	BitRateMode BitRateMode
	BitRate     BitRate
	ChannelMode mp3.ChannelMode
}

ConversionConfig holds the desired conversion for an audio file.

func BindConversionConfig

func BindConversionConfig(c *gin.Context) (ConversionConfig, error)

BindConversionConfig captures and validates a ConversionConfig passed in query parameters.

func (ConversionConfig) ToQueryValues

func (cfg ConversionConfig) ToQueryValues() url.Values

ToQueryValues translates a ConversionCongig to the same query parameters expected by BindConversionConfig.

type Page

type Page struct {
	Num   int
	Title int
}

Page represents a page in a sequence of paginated results.

type Pagination

type Pagination struct {
	// contains filtered or unexported fields
}

Pagination represents a location in a sequences of paginated results.

func (Pagination) CurrentPage

func (p Pagination) CurrentPage() int

CurrentPage returns the current page in the result set.

func (Pagination) FirstItem

func (p Pagination) FirstItem() int

FirstItem returns the offset of the first item for the current page in the result set.

func (Pagination) LastPage

func (p Pagination) LastPage() int

LastPage returnss the last page in the result set.

func (Pagination) NextPage

func (p Pagination) NextPage() int

NextPage returns the subsequent page in the result set.

func (Pagination) NumPages

func (p Pagination) NumPages() int

NumPages returns the number of pages in the result set.

func (Pagination) Pages

func (p Pagination) Pages() []Page

Pages returns a slide of Page elements.

func (Pagination) PreviousPage

func (p Pagination) PreviousPage() int

PreviousPage returns the preceding page in the result set.