15 KiB
podcast
import "github.com/eduncan911/podcast"
Overview
Package podcast is an iTunes and RSS 2.0 podcast generator for GoLang that enforces strict compliance by using its simple interface.
Full documentation with detailed examples located at https://godoc.org/github.com/eduncan911/podcast
Usage
$ go get -u github.com/eduncan911/podcast
The API exposes a number of method receivers on structs that implements the logic required to comply with the specifications and ensure a compliant feed. A number of overrides occur to help with iTunes visibility of your episodes.
Notably, the Podcast.AddItem(i Item) function performs most of the heavy lifting by taking the Item input and performing validation, overrides and duplicate setters through the feed.
See the detailed Examples in the GoDocs for complete usage.
Extensibility
In no way are you restricted in having full control over your feeds. You may choose to skip the API methods and instead use the structs directly. The fields have been grouped by RSS 2.0 and iTunes fields.
iTunes specific fields are all prefixed with the letter I
.
References
RSS 2.0: https://cyber.harvard.edu/rss/rss.html
Podcasts: https://help.apple.com/itc/podcasts_connect/#/itca5b22233
Index
- type Author
- type Enclosure
- type EnclosureType
- type ICategory
- type IImage
- type Image
- type Item
- type Podcast
- func New(title, link, description string, pubDate, lastBuildDate *time.Time) Podcast
- func (p *Podcast) AddAuthor(name, email string)
- func (p *Podcast) AddCategory(category string, subCategories []string)
- func (p *Podcast) AddImage(url string)
- func (p *Podcast) AddItem(i Item) (int, error)
- func (p *Podcast) Bytes() []byte
- func (p *Podcast) Encode(w io.Writer) error
- func (p *Podcast) String() string
- func (p *Podcast) Write(b []byte) (n int, err error)
- type TextInput
Examples
- Package
- New
- Podcast.AddAuthor
- Podcast.AddCategory
- Podcast.AddImage
- Podcast.AddItem
- Podcast.Bytes
- Package (HttpHandlers)
Package files
author.go doc.go enclosure.go image.go item.go itunes.go podcast.go textinput.go
type Author
type Author struct {
XMLName xml.Name `xml:"itunes:owner"`
Name string `xml:"itunes:name"`
Email string `xml:"itunes:email"`
}
Author represents a named author and email.
For iTunes compliance, both Name and Email are required.
type Enclosure
type Enclosure struct {
XMLName xml.Name `xml:"enclosure"`
URL string `xml:"url,attr"`
Length int64 `xml:"-"`
LengthFormatted string `xml:"length,attr"`
Type EnclosureType `xml:"-"`
TypeFormatted string `xml:"type,attr"`
}
Enclosure represents a download enclosure.
type EnclosureType
type EnclosureType int
EnclosureType specifies the type of the enclosure.
const (
M4A EnclosureType = iota
M4V
MP4
MP3
MOV
PDF
EPUB
)
EnclosureType specifies the type of the enclosure.
func (EnclosureType) String
func (et EnclosureType) String() string
String returns the MIME type encoding of the specified EnclosureType.
type ICategory
type ICategory struct {
XMLName xml.Name `xml:"itunes:category"`
Text string `xml:"text,attr"`
ICategories []*ICategory
}
ICategory is a 2-tier classification system for iTunes.
type IImage
type IImage struct {
XMLName xml.Name `xml:"itunes:image"`
HREF string `xml:"href,attr"`
}
IImage represents an iTunes image.
Podcast feeds contain artwork that is a minimum size of 1400 x 1400 pixels and a maximum size of 3000 x 3000 pixels, 72 dpi, in JPEG or PNG format with appropriate file extensions (.jpg, .png), and in the RGB colorspace. To optimize images for mobile devices, Apple recommends compressing your image files.
type Image
type Image struct {
XMLName xml.Name `xml:"image"`
// TODO: is it URL or Link? which is it?
URL string `xml:"url"`
Title string `xml:"title,omitempty"`
Link string `xml:"link,omitempty"`
Width int `xml:"width,omitempty"`
Height int `xml:"height,omitempty"`
}
Image represents an image.
Podcast feeds contain artwork that is a minimum size of 1400 x 1400 pixels and a maximum size of 3000 x 3000 pixels, 72 dpi, in JPEG or PNG format with appropriate file extensions (.jpg, .png), and in the RGB colorspace. To optimize images for mobile devices, Apple recommends compressing your image files.
type Item
type Item struct {
XMLName xml.Name `xml:"item"`
GUID string `xml:"guid"`
Title string `xml:"title"`
Link string `xml:"link"`
Description string `xml:"description"`
Author *Author `xml:"-"`
AuthorFormatted string `xml:"author,omitempty"`
Category string `xml:"category,omitempty"`
Comments string `xml:"comments,omitempty"`
Source string `xml:"source,omitempty"`
PubDate *time.Time `xml:"-"`
PubDateFormatted string `xml:"pubDate,omitempty"`
Enclosure *Enclosure
// https://help.apple.com/itc/podcasts_connect/#/itcb54353390
IAuthor string `xml:"itunes:author,omitempty"`
ISubtitle string `xml:"itunes:subtitle,omitempty"`
// TODO: CDATA
ISummary string `xml:"itunes:summary,omitempty"`
IImage *IImage
IDuration string `xml:"itunes:duration,omitempty"`
IExplicit string `xml:"itunes:explicit,omitempty"`
IIsClosedCaptioned string `xml:"itunes:isClosedCaptioned,omitempty"`
IOrder string `xml:"itunes:order,omitempty"`
}
Item represents a single entry in a podcast.
Article minimal requirements are:
- Title
- Description
- Link
Audio minimal requirements are:
- Title
- Description
- Enclosure (HREF, Type and Length all required)
Recommendations:
- Setting the minimal fields sets most of other fields, including iTunes.
- Use the Published time.Time setting instead of PubDate.
- Always set an Enclosure.Length, to be nice to your downloaders.
- Use Enclosure.Type instead of setting TypeFormatted for valid extensions.
func (*Item) AddEnclosure
func (i *Item) AddEnclosure(
url string, enclosureType EnclosureType, lengthInSeconds int64)
AddEnclosure adds the downloadable asset to the podcast Item.
type Podcast
type Podcast struct {
XMLName xml.Name `xml:"channel"`
Title string `xml:"title"`
Link string `xml:"link"`
Description string `xml:"description"`
Category string `xml:"category,omitempty"`
Cloud string `xml:"cloud,omitempty"`
Copyright string `xml:"copyright,omitempty"`
Docs string `xml:"docs,omitempty"`
Generator string `xml:"generator,omitempty"`
Language string `xml:"language,omitempty"`
LastBuildDate string `xml:"lastBuildDate,omitempty"`
ManagingEditor string `xml:"managingEditor,omitempty"`
PubDate string `xml:"pubDate,omitempty"`
Rating string `xml:"rating,omitempty"`
SkipHours string `xml:"skipHours,omitempty"`
SkipDays string `xml:"skipDays,omitempty"`
TTL int `xml:"ttl,omitempty"`
WebMaster string `xml:"webMaster,omitempty"`
Image *Image
TextInput *TextInput
// https://help.apple.com/itc/podcasts_connect/#/itcb54353390
IAuthor string `xml:"itunes:author,omitempty"`
ISubtitle string `xml:"itunes:subtitle,omitempty"`
// TODO: CDATA
ISummary string `xml:"itunes:summary,omitempty"`
IBlock string `xml:"itunes:block,omitempty"`
IImage *IImage
IDuration string `xml:"itunes:duration,omitempty"`
IExplicit string `xml:"itunes:explicit,omitempty"`
IComplete string `xml:"itunes:complete,omitempty"`
INewFeedURL string `xml:"itunes:new-feed-url,omitempty"`
IOwner *Author // Author is formatted for itunes as-is
ICategories []*ICategory
Items []*Item
}
Podcast represents a podcast.
func New
func New(title, link, description string,
pubDate, lastBuildDate *time.Time) Podcast
New instantiates a Podcast with required parameters.
Nil-able fields are optional but recommended as they are formatted to the expected proper formats.
func (*Podcast) AddAuthor
func (p *Podcast) AddAuthor(name, email string)
AddAuthor adds the specified Author to the podcast.
func (*Podcast) AddCategory
func (p *Podcast) AddCategory(category string, subCategories []string)
AddCategory adds the categories to the Podcast in comma delimited format.
subCategories are optional.
func (*Podcast) AddImage
func (p *Podcast) AddImage(url string)
AddImage adds the specified Image to the Podcast.
Podcast feeds contain artwork that is a minimum size of 1400 x 1400 pixels and a maximum size of 3000 x 3000 pixels, 72 dpi, in JPEG or PNG format with appropriate file extensions (.jpg, .png), and in the RGB colorspace. To optimize images for mobile devices, Apple recommends compressing your image files.
func (*Podcast) AddItem
func (p *Podcast) AddItem(i Item) (int, error)
AddItem adds the podcast episode. It returns a count of Items added or any errors in validation that may have occurred.
This method takes the "itunes overrides" approach to populating itunes tags according to the overrides rules in the specification. This not only complies completely with iTunes parsing rules; but, it also displays what is possible to be set on an individual episode level - if you wish to have more fine grain control over your content.
This method imposes strict validation of the Item being added to confirm to Podcast and iTunes specifications.
Article minimal requirements are:
- Title
- Description
- Link
Audio, Video and Downloads minimal requirements are:
- Title
- Description
- Enclosure (HREF, Type and Length all required)
The following fields are always overwritten (don't set them):
- GUID
- PubDateFormatted
- AuthorFormatted
- Enclosure.TypeFormatted
- Enclosure.LengthFormatted
Recommendations:
-
Just set the minimal fields: the rest get set for you.
-
Always set an Enclosure.Length, to be nice to your downloaders.
-
Follow Apple's best practices to enrich your podcasts:
-
For specifications of itunes tags, see:
func (*Podcast) Bytes
func (p *Podcast) Bytes() []byte
Bytes returns an encoded []byte slice.
func (*Podcast) Encode
func (p *Podcast) Encode(w io.Writer) error
Encode writes the bytes to the io.Writer stream in RSS 2.0 specification.
func (*Podcast) String
func (p *Podcast) String() string
String encodes the Podcast state to a string.
func (*Podcast) Write
func (p *Podcast) Write(b []byte) (n int, err error)
Write implements the io.Writer interface to write an RSS 2.0 stream that is compliant to the RSS 2.0 specification.
type TextInput
type TextInput struct {
XMLName xml.Name `xml:"textInput"`
Title string `xml:"title"`
Description string `xml:"description"`
Name string `xml:"name"`
Link string `xml:"link"`
}
TextInput represents text inputs.
Generated by godoc2md