podcast

Documentation

Overview

Package podcast reads public podcast directories and publisher feeds.

Index

• Variables
• func Country(s string) (string, error)
• func Duration(s string) float64
• func Text(s string) string
• func ValidURL(raw string) bool
• type Category
• type Client
  • func NewClient() *Client
  • func (c *Client) Feed(ctx context.Context, raw string) (Feed, error)
  • func (c *Client) Search(ctx context.Context, query, genre string) ([]Show, error)
  • func (c *Client) Top(ctx context.Context, country string) ([]Show, error)
• type Episode
  • func (e Episode) Key() string
• type Feed
• type Show

Variables

var Categories = []Category{
	{"1301", "Arts"}, {"1321", "Business"}, {"1303", "Comedy"}, {"1304", "Education"},
	{"1483", "Fiction"}, {"1511", "Government"}, {"1512", "Health & Fitness"}, {"1487", "History"},
	{"1305", "Kids & Family"}, {"1502", "Leisure"}, {"1310", "Music"}, {"1489", "News"},
	{"1314", "Religion & Spirituality"}, {"1533", "Science"}, {"1324", "Society & Culture"},
	{"1545", "Sports"}, {"1318", "Technology"}, {"1488", "True Crime"}, {"1309", "TV & Film"},
}

Categories lists the 19 top-level genres in display order.

Functions

func Country

func Country(s string) (string, error)

Country validates and lowercases a two-letter chart country code.

func Duration

func Duration(s string) float64

Duration parses seconds, MM:SS or HH:MM:SS; invalid values return zero.

func Text

func Text(s string) string

Text strips markup and terminal control characters from publisher metadata.

func ValidURL

func ValidURL(raw string) bool

ValidURL accepts absolute HTTP(S) addresses without embedded credentials.

Types

type Category

type Category struct {
	// ID is Apple's genre identifier.
	ID string `json:"id"`
	// Name is the display name and discovery search term.
	Name string `json:"name"`
}

Category names a supported podcast directory genre.

type Client

type Client struct {
	// HTTP supplies request deadlines and redirect policy.
	HTTP *http.Client
	// DirectoryURL is the search and lookup service base URL.
	DirectoryURL string
	// ChartsURL is the chart service base URL.
	ChartsURL string
}

Client retrieves podcast discovery data and RSS feeds with bounded requests.

func NewClient

func NewClient() *Client

NewClient configures public discovery endpoints and a 30-second timeout.

func (*Client) Feed

func (c *Client) Feed(ctx context.Context, raw string) (Feed, error)

Feed reads up to 300 playable RSS or Atom episodes from a publisher URL.

func (*Client) Search

func (c *Client) Search(ctx context.Context, query, genre string) ([]Show, error)

Search finds up to 100 shows, optionally restricted to a genre ID.

func (*Client) Top

func (c *Client) Top(ctx context.Context, country string) ([]Show, error)

Top resolves a country's top 100 chart to unique feeds in ranking order.

type Episode

type Episode struct {
	// FeedURL scopes episode identifiers to their originating show.
	FeedURL string `json:"feed_url"`
	// GUID is the publisher identifier, if provided.
	GUID string `json:"guid,omitempty"`
	// Title is the episode's plain-text name.
	Title string `json:"title"`
	// Show is the display name of the parent podcast.
	Show string `json:"show"`
	// Author identifies the podcast publisher or host.
	Author string `json:"author,omitempty"`
	// Artwork is the parent podcast's image URL.
	Artwork string `json:"artwork,omitempty"`
	// URL points to the encoded audio enclosure.
	URL string `json:"url"`
	// Published is the publication date, or zero when unknown.
	Published time.Time `json:"published,omitzero"`
	// Duration is the publisher's length estimate in seconds.
	Duration float64 `json:"duration,omitempty"`
	// Description is a plain-text episode summary.
	Description string `json:"description,omitempty"`
}

Episode identifies a finite audio item independently of the playback process.

func (Episode) Key

func (e Episode) Key() string

Key survives publisher changes to signed media URLs whenever the feed has a GUID, or a title and publication date. Feed identity scopes publisher IDs.

type Feed

type Feed struct {
	// Show describes the feed's publisher metadata.
	Show Show `json:"show"`
	// Episodes contains at most 300 playable items.
	Episodes []Episode `json:"episodes"`
}

Feed contains a show's metadata and playable episodes in publisher order.

type Show

type Show struct {
	// ID is the directory identifier, empty for a directly opened feed.
	ID string `json:"id,omitempty"`
	// Title is the display name of the show.
	Title string `json:"title"`
	// Author identifies the publisher or host.
	Author string `json:"author,omitempty"`
	// FeedURL is the stable subscription address.
	FeedURL string `json:"feed_url"`
	// Artwork is the optional publisher image URL.
	Artwork string `json:"artwork,omitempty"`
}

Show is a publisher's podcast and the feed used to retrieve its episodes.