podcast

Package podcast generates a fully compliant iTunes and RSS 2.0 podcast feed for GoLang using a simple API.

Full documentation with detailed examples located at https://godoc.org/github.com/cykor/podcast

Usage

To use, go get and import the package like your typical GoLang library.

$ go get -u github.com/cykor/podcast

import "github.com/cykor/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.

Full detailed Examples of the API are at https://godoc.org/github.com/cykor/podcast.

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

Final Release

This project is now in maintenance mode. This means no more planned releases expected.

With the success of 6 iTunes-accepted podcasts I have published with this library, and with the feedback from the community, this library is now considered stable and complete.

Feel free to open an issue, file a bug or suggest a non-breaking enhancement and I will address it as soon as possible.

Thank you!

Release Notes

2.0.1

Only change GUID if it's nil (podcast.go)
bump pVersion to 2.0.1

2.0.0

remove all instances of *time.Time from the API and replace them by time.Time by value
go mod

1.3.1

increased itunes compliance after feedback from Apple:

specified what categories should be set with AddCategory().
enforced title and link as part of Image.

added Podcast.AddAtomLink() for more broad compliance to readers.

1.3.0

fixes Item.Duration being set incorrectly.
changed Item.AddEnclosure() parameter definition (Bytes not Seconds!).
added Item.AddDuration formatting and override.
added more documentation surrounding Item.Enclosure{}

1.2.1

added Podcast.AddSubTitle() and truncating to 64 chars.
added a number of Guards to protect against empty fields.

1.2.0

added Podcast.AddPubDate() and Podcast.AddLastBuildDate() overrides.
added Item.AddImage() to mask some cumbersome addition of IImage.
added Item.AddPubDate to simply datetime setters.
added more examples (mostly around Item struct).
tweaked some documentation.

1.1.0

Enabling CDATA in ISummary fields for Podcast and Channel.

1.0.0

Initial release.
Full documentation, full examples and complete code coverage.

Imported Packages

github.com/pkg/errors

Index

type AtomLink
type Author
type Enclosure
type EnclosureType
- func (et EnclosureType) String() string
type ICategory
type IImage
type ISummary
type Image
type Item
type Podcast
type TextInput

Package files

atomlink.go author.go doc.go enclosure.go image.go item.go itunes.go podcast.go textinput.go

type AtomLink

type AtomLink struct {
    XMLName xml.Name `xml:"atom:link"`
    HREF    string   `xml:"href,attr"`
    Rel     string   `xml:"rel,attr"`
    Type    string   `xml:"type,attr"`
}

AtomLink represents the Atom reference link.

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 is the downloadable url for the content. (Required)
    URL string `xml:"url,attr"`

    // Length is the size in Bytes of the download. (Required)
    Length int64 `xml:"-"`
    // LengthFormatted is the size in Bytes of the download. (Required)
    //
    // This field gets overwritten with the API when setting Length.
    LengthFormatted string `xml:"length,attr"`

    // Type is MIME type encoding of the download. (Required)
    Type EnclosureType `xml:"-"`
    // TypeFormatted is MIME type encoding of the download. (Required)
    //
    // This field gets overwritten with the API when setting Type.
    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 ISummary

type ISummary struct {
    XMLName xml.Name `xml:"itunes:summary"`
    Text    string   `xml:",cdata"`
}

ISummary is a 4000 character rich-text field for the itunes:summary tag.

This is rendered as CDATA which allows for HTML tags such as .

type Image

type Image struct {
    XMLName     xml.Name `xml:"image"`
    URL         string   `xml:"url"`
    Title       string   `xml:"title"`
    Link        string   `xml:"link"`
    Description string   `xml:"description,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"`
    ISummary           *ISummary
    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) AddDuration

func (i *Item) AddDuration(durationInSeconds int64)

AddDuration adds the duration to the iTunes duration field.

func (*Item) AddEnclosure

func (i *Item) AddEnclosure(
    url string, enclosureType EnclosureType, lengthInBytes int64)

AddEnclosure adds the downloadable asset to the podcast Item.

func (*Item) AddImage

func (i *Item) AddImage(url string)

AddImage adds the image as an iTunes-only IImage. RSS 2.0 does not have the specification of Images at the Item level.

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 (*Item) AddPubDate

func (i *Item) AddPubDate(datetime time.Time)

AddPubDate adds the datetime as a parsed PubDate.

UTC time is used by default.

func (*Item) AddSummary

func (i *Item) AddSummary(summary string)

AddSummary adds the iTunes summary.

Limit: 4000 characters

Note that this field is a CDATA encoded field which allows for rich text such as html links: <a href="http://www.apple.com">Apple.

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
    AtomLink       *AtomLink

    // https://help.apple.com/itc/podcasts_connect/#/itcb54353390
    IAuthor     string `xml:"itunes:author,omitempty"`
    ISubtitle   string `xml:"itunes:subtitle,omitempty"`
    ISummary    *ISummary
    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
    // contains filtered or unexported fields
}

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) AddAtomLink

func (p *Podcast) AddAtomLink(href string)

AddAtomLink adds a FQDN reference to an atom feed.

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 category to the Podcast.

ICategory can be listed multiple times.

Calling this method multiple times will APPEND the category to the existing list, if any, including ICategory.

Note that Apple iTunes has a specific list of categories that only can be used and will invalidate the feed if deviated from the list. That list is as follows.

Arts

Design
Fashion & Beauty
Food
Literature
Performing Arts
Visual Arts Business
Business News
Careers
Investing
Management & Marketing
Shopping Comedy Education
Education Technology
Higher Education
K-12
Language Courses
Training Games & Hobbies
Automotive
Aviation
Hobbies
Other Games
Video Games Government & Organizations
Local
National
Non-Profit
Regional Health
Alternative Health
Fitness & Nutrition
Self-Help
Sexuality Kids & Family Music News & Politics Religion & Spirituality
Buddhism
Christianity
Hinduism
Islam
Judaism
Other
Spirituality Science & Medicine
Medicine
Natural Sciences
Social Sciences Society & Culture
History
Personal Journals
Philosophy
Places & Travel Sports & Recreation
Amateur
College & High School
Outdoor
Professional Technology
Gadgets
Podcasting
Software How-To
Tech News TV & Film

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:

https://help.apple.com/itc/podcasts_connect/#/itc2b3780e76
For specifications of itunes tags, see:

https://help.apple.com/itc/podcasts_connect/#/itcb54353390

func (*Podcast) AddLastBuildDate

func (p *Podcast) AddLastBuildDate(datetime time.Time)

AddLastBuildDate adds the datetime as a parsed PubDate.

UTC time is used by default.

func (*Podcast) AddPubDate

func (p *Podcast) AddPubDate(datetime time.Time)

AddPubDate adds the datetime as a parsed PubDate.

UTC time is used by default.

func (*Podcast) AddSubTitle

func (p *Podcast) AddSubTitle(subTitle string)

AddSubTitle adds the iTunes subtitle that is displayed with the title in iTunes.

Note that this field should be just a few words long according to Apple. This method will truncate the string to 64 chars if too long with "..."

func (*Podcast) AddSummary

func (p *Podcast) AddSummary(summary string)

AddSummary adds the iTunes summary.

Limit: 4000 characters

Note that this field is a CDATA encoded field which allows for rich text such as html links: <a href="http://www.apple.com">Apple.

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.

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 godoc2ghmd

Name		Name	Last commit message	Last commit date
Latest commit History 76 Commits
.gitignore		.gitignore
.travis.yml		.travis.yml
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
atomlink.go		atomlink.go
author.go		author.go
doc.go		doc.go
enclosure.go		enclosure.go
enclosure_test.go		enclosure_test.go
example_test.go		example_test.go
examples_test.go		examples_test.go
go.mod		go.mod
go.sum		go.sum
image.go		image.go
item.go		item.go
item_test.go		item_test.go
itunes.go		itunes.go
podcast.go		podcast.go
podcast_internals_test.go		podcast_internals_test.go
podcast_test.go		podcast_test.go
textinput.go		textinput.go

License

cykor/podcast

Folders and files

Latest commit

History

Repository files navigation

podcast

Usage

Extensibility

References

Final Release

Release Notes

Table of Contents

func (EnclosureType) String

func (*Item) AddDuration

func (*Item) AddEnclosure

func (*Item) AddImage

func (*Item) AddPubDate

func (*Item) AddSummary

func (*Podcast) AddAtomLink

func (*Podcast) AddAuthor

func (*Podcast) AddCategory

func (*Podcast) AddImage

func (*Podcast) AddItem

func (*Podcast) AddLastBuildDate

func (*Podcast) AddPubDate

func (*Podcast) AddSubTitle

func (*Podcast) AddSummary

func (*Podcast) Bytes

func (*Podcast) Encode

func (*Podcast) String

About

Resources

License

Stars

Watchers

Forks

Languages