Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/bcomnes/jsonfeed-to-rss

📡Convert a jsonfeed to an RSS 2.0 feed with iTunes extensions
https://github.com/bcomnes/jsonfeed-to-rss
Last synced: about 2 months ago
JSON representation
📡Convert a jsonfeed to an RSS 2.0 feed with iTunes extensions
Host: GitHub
URL: https://github.com/bcomnes/jsonfeed-to-rss
Owner: bcomnes
License: mit
Created: 2018-05-30T01:45:54.000Z (over 6 years ago)
Default Branch: master
Last Pushed: 2024-06-10T20:19:31.000Z (3 months ago)
Last Synced: 2024-07-21T04:02:19.960Z (2 months ago)
Language: JavaScript
Homepage: https://jsonfeed-to-rss.netlify.com
Size: 661 KB
Stars: 38
Watchers: 4
Forks: 12
Open Issues: 8
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project

README

        # jsonfeed-to-rss

[![npm version][2]][3] [![build status][4]][5]

[![downloads][8]][9] [![js-standard-style][10]][11]

Convert a JSON feed to an rss feed ([RSS 2.0.11][rss]).  Supports the [@xmlns:itunes][itunes] iTunes RSS extensions and [best practices for podcasts][bp], [xmlns:dc][dc] Dublin Core author names, and the [xmlns:content][content] RDF Site Summary 1.0 Modules: Content encoded content extension.

![JSON feed icon](/reference/icon.png)

## Installation

```console

$ npm install jsonfeed-to-rss

```

## Usage

```js

const jsonfeedToRSS = require('jsonfeed-to-rss')

const someJSONFeed = require('./load-some-json-feed-data.json')

const rssFeed = jsonfeedToRSS(someJSONFeed) // Returns an rss 2.0.11 formatted json feed

```

Example input:

```json

{

  "version":"https://jsonfeed.org/version/1",

  "title":"bret.io log",

  "home_page_url":"https://jsonfeed-to-rss.netlify.com",

  "feed_url":"https://jsonfeed-to-rss.netlify.com/snapshots/readme-feed.json",

  "description": "A simple summary that describes the podcast.  It can have a few sentences.\n\nIf there is more than one paragraph, it gets truncated in some contexts.",

  "next_url":"https://jsonfeed-to-rss.netlify.com/snapshots/2017.json",

  "icon":"https://jsonfeed-to-rss.netlify.com/icon-512x512.png",

  "author":{

     "name":"Bret Comnes",

     "url":"https://bret.io",

     "avatar":"https://gravatar.com/avatar/8d8b82740cb7ca994449cccd1dfdef5f?size=512"

  },

  "_itunes":{

     "about":"https://github.com/bcomnes/jsonfeed-to-rss#itunes",

     "owner": {

       "email": "[email protected]"

     },

     "image": "https://jsonfeed-to-rss.netlify.com/icon-3000x3000.png",

     "category": "Sports & Recreation",

     "subcategory": "Outdoor"

  },

  "items":[

     {

        "date_published":"2018-04-07T20:48:02.000Z",

        "content_html":"
Curam ad aut hactenus dentes cedere vigil
\nNon Clitorio vertitur cavatur
\nLorem markdownum edendi, non ad clamant solacia septem ambierantque. Scelus te\nmihi arcum fore nitidam; in dixit de simul.",

        "url":"https://jsonfeed-to-rss.netlify.com/a-url-to-a-post",

        "id":"https://jsonfeed-to-rss.netlify.com/a-url-to-a-post-2018-04-07T20:48:02.000Z",

        "image": "https://jsonfeed-to-rss.netlify.com/a-url-to-a-post/episode-3000x3000.png",

        "_itunes": {

          "episode": 12

        },

        "attachments":[

           {

              "url":"https://jsonfeed-to-rss.netlify.com/a-url-to-a-post/attatchment.mp4",

              "mime_type":"audio/mpeg",

              "title":"Hey this is a podcast episode",

              "duration_in_seconds":12345,

              "size_in_bytes":1234

           }

        ]

     }

  ]

}

```

Example output:

```xml

  

    

    bret.io log

    https://jsonfeed-to-rss.netlify.com

    A simple summary that describes the podcast.  It can have a few sentences.

If there is more than one paragraph, it gets truncated in some contexts.

    en-us

    © 2018 Bret Comnes

    Sat, 07 Apr 2018 20:48:02 GMT

    Sports & Recreation

    Outdoor

    jsonfeed-to-rss 1.1.1 (https://github.com/bcomnes/jsonfeed-to-rss#readme)

    http://www.rssboard.org/rss-specification

    

      https://jsonfeed-to-rss.netlify.com/icon-512x512.png

      https://jsonfeed-to-rss.netlify.com

      bret.io log

    

    Bret Comnes

    A simple summary that describes the podcast.  It can have a few sentences.

    A simple summary that describes the podcast.

    episodic

    

      Bret Comnes

      [email protected]

    

    

    

      

    

    

      Curam ad aut hactenus dentes cedere vigil

      https://jsonfeed-to-rss.netlify.com/a-url-to-a-post

      Bret Comnes

      Curam ad aut hactenus dentes cedere vigil

Non Clitorio vertitur cavatur

Lorem markdownum edendi, non ad clamant solacia septem ambierantque. Scelus te

mihi arcum fore nitidam; in dixit de simul.

      

        Curam ad aut hactenus dentes cedere vigil

Non Clitorio vertitur cavatur

Lorem markdownum edendi, non ad clamant solacia septem ambierantque. Scelus te

mihi arcum fore nitidam; in dixit de simul.]]>

      

      https://jsonfeed-to-rss.netlify.com/a-url-to-a-post-2018-04-07T20:48:02.000Z

      Sat, 07 Apr 2018 20:48:02 GMT

      

      full

      Curam ad aut hactenus dentes cedere vigil

      Bret Comnes

      12

      Curam ad aut hactenus dentes cedere vigil

      Curam ad aut hactenus dentes cedere vigil

      https://jsonfeed-to-rss.netlify.com/a-url-to-a-post/episode-3000x3000.png

      3:25:45

    

  

```

## API

### `jsonfeedToRSS(parsedJsonfeed, opts)`

Coverts a parsed JSON feed into an RSS feed.  Returns the string of the rss feed.

Opts include:

```js

{

  // a function that returns the rss feed url

  feedURLFn: (feedURL, jf) => feedURL.replace(/\.json\b/, '-rss.xml'),

  language: 'en-us',

  copyright: `© ${now.getFullYear()} ${jf.author && jf.author.name ? jf.author.name : ''}`,

  managingEditor,

  webMaster,

  idIsPermalink: false, // if guid is the permalink, you can set this true

  category, // array of categories.. will attempt to use iTunes categories if available

  ttl,

  skipHours,

  skipDays,

  itunes: !!jf._itunes // generate RSS feed with iTunes extensions

}

```

## [Dublin Core Extensions][dc]

There is only one mapping implemented between jsonfeed and RSS:

### Items

- `item.author.name || jf.author.name` (recommended) maps to `dc:creator`.

## [RDF Site Summary Extensions][content]

The `content:encoded` field is used to store an `html` representation of content, and RSS's default `description` field is for a plain text representation.

### Items

- `item.content_html` (recommended) maps to a `CDATA` encoded `content:encoded` node.

- `item.content_text || striptags(item.content_html)` (recommended) maps to an escaped `description` node.  When creating an iTunes feed, description is truncated to 4000 characters.

## [iTunes Extensions][itunes]

If the `itunes` option is set to `true` (or if the `jsonfeed._itunes` extension object is included in the jsonfeed) the resulting RSS feed will include as many itunes extension tags as possible.  You can override/set `_itunes` extension fields from the `opts.itunes` object.

All `_itunes.property` map directly to the RSS `itunes:property` extensions, but most have default mappings to standard JSONFeed properties. Its better to rely on the [default JSONFeed fields](https://jsonfeed.org/version/1), but you can override these mappings by including explicit `_itunes` extension properties in your JSONFeed.

- There are a few extension fields that SHOULD be included, but dont map well.  These are marked as (recommended).

- There are fields that dont have a mapping that are definitely optional but CAN be included. These are marked as (optional).

- There are fields that have default and acceptable mappings.  These MAY be included but probably not.  These are marked as (mapped).

### Top-level

- `_itunes.owner.email` (recommended) maps to `itunes:owner.itunes:email`.

- `_itunes.image` (recommended) maps to `itunes:image`.  Defaults to `icon` but the `icon` field does not meet the minimum requirements for this field.  The `icon` field is a 512x512 image, where iTunes recommends Artwork that must be a minimum size of 1400 x 1400 pixels and a maximum size of 3000 x 3000 pixels, in JPEG or PNG format, 72 dpi, with appropriate file extensions (.jpg, .png), and in the RGB colorspace.

- `_itunes.category` (recommended) maps to `itunes:category`.  Defaults to `opts.category[0]`.  Must be a [valid category][categories].

- `_itunes.subcategory` (recommended) maps to `itunes:category:itunes:category`.  Defaults to `opts.category[1]`. Must be a [valid subcategory][categories].

- `_itunes.explicit` (recommended) maps to `itunes:explicit`.  Defaults to unset.

- `_itunes.type` (optional) maps to `itunes:type`.  Defaults to `episodic` (newest first).  The other option is `serial` (oldest first). [Details][bp].

- `_itunes.complete` (optional) maps to `itunes:complete`.  Defaults to null.  Tells podcast clients to stop updating this feed ️️️forever. ⚠️

- `_itunes.block` (optional) maps to `itunes:block`.  Defaults to null.  Prevents the feed from being added to Apple's podcast directory.  Helpful for private or customer specific feeds.

- `_itunes.new_feed_url` (optional) maps to `itunes:new-feed-url`.  Used for moving feeds from an old url to a new url. See https://podcasters.apple.com/support/837-change-the-rss-feed-url for more details.

- `_itunes.author` (mapped) maps to `itunes:author`.  Defaults to `author.name`.

- `_itunes.summary` (mapped) maps to `itunes:summary`.  Defaults to the first paragraph of the generated `description` rss field.

- `_itunes.subtitle` (mapped) maps to `itunes:subtitle`.  Defaults to the first sentence of the generated `itunes:summary`.

- `_itunes.owner.name` (mapped) maps to `itunes:owner.itunes:name`.  Defaults to `author.name`.

### Items

- `_itunes.episode` (recommended) maps to `itunes:episode`.  No fallback. Must be an integer > 0.  Its recommended you put episode numbers here, instead of in the title.

- `_itunes.season` (optional) maps to `itunes:season`.

- `_itunes.episode_type` (optional) maps to `itunes:episodeType`, but must be one of `full`, `trailer`, or `bonus`.  Defaults to `full`.

- `_itunes.block` (optional) maps to `itunes:block`.  Defaults to null.  Prevents the item from being added to Apple's podcast directory. "For example, you might want to block a specific episode if you know that its content would otherwise cause the entire podcast to be removed from Apple Podcasts."

- `_itunes.is_closed_captioned` (optional) maps to `itunes:isClosedCaptioned`.

- `_itunes.explicit` (optional) maps to `itunes:explicit`.  Defaults to null.

- `_itunes.title` (mapped) maps to `itunes:title`.  Falls back to `item.title` and then the `generateTitle` function.

- `_itunes.author` (mapped) maps to `itunes:author`.  Falls back to `author.name || jf._itunes.author || jf.author.name`.

- `_itunes.subtitle` (mapped) maps to `itunes:subtitle`.  Defaults to the first sentence of the generated `_itunes.summary`.

- `_itunes.summary` (mapped) maps to `itunes:summary`.  Defaults to the first paragraph of the generated plaintext description of the item.

- `_itunes.duration` (mapped) maps to `itunes:duration`. Defaults to `attachment.duration_in_seconds` formatted as HH:MM:SS.

- `_itunes.image` (mapped) maps to `itunes:image`.  Defaults to `image`.  Artwork must be a minimum size of 1400 x 1400 pixels and a maximum size of 3000 x 3000 pixels, in JPEG or PNG format, 72 dpi, with appropriate file extensions (.jpg, .png), and in the RGB colorspace.  JSONFeed has no defined image restrictions on the `image` field, so it can be safely used for this purpose.

## See also

- [JSON Feed: Mapping RSS and Atom to JSON Feed](https://jsonfeed.org/mappingrssandatom)

- [rssboard.org/rss-specification](http://www.rssboard.org/rss-specification)

- [Really Simple Syndication Best Practices Profile](http://www.rssboard.org/rss-profile#namespace-elements-content-encoded)

- [RSS validator.w3.org](https://validator.w3.org/feed/docs/rss2.html)

- [AtomEnabled: Developers > Syndication](https://web.archive.org/web/20160113103647/http://atomenabled.org/developers/syndication/#link)

- [Why RSS Content Module is Popular](https://developer.mozilla.org/en-US/docs/Web/RSS/Article/Why_RSS_Content_Module_is_Popular_-_Including_HTML_Contents)

### Related projects

- [bcomnes/jsonfeed-to-atom](https://github.com/bcomnes/jsonfeed-to-atom)

- [bcomnes/generate-feed](https://github.com/bcomnes/generate-feed)

### More iTunes RSS feed information

- [RSS tags for Podcasts Connect][itunes]

- [Podcast best practices][bp]

- [Podcasts Connect categories][categories]

  - [bcomnes/podcast-categories](https://github.com/bcomnes/podcast-categories)

- [Apple Create a podcast](https://help.apple.com/itc/podcasts_connect/#/itca5b22233a)

- [Apple RSS feed sample](https://help.apple.com/itc/podcasts_connect/#/itcbaf351599)

  - [reference/podcast.xml](reference/podcast.xml)

- [Apple Requirements - Podcasts Connect Help](https://help.apple.com/itc/podcasts_connect/#/itc1723472cb)

- [Apple Podcasts - What’s New in iOS 11 - 2017](http://podcasts.apple.com/resources/spec/ApplePodcastsSpecUpdatesiOS11.pdf) ([mirror](reference/ApplePodcastsSpecUpdatesiOS11.pdf))

- [Apple Podcasts Identity Guidelines](https://www.apple.com/itunes/marketing-on-podcasts/identity-guidelines.html#messaging-and-style)

- [podbase Podcast Validator](https://podba.se/validate/)

- [Apple podcasts: Whats new](https://itunespartner.apple.com/podcasts/whats-new/)

### Reference RSS feeds

- [reference/datcast.xml](reference/datcast.xml)

- [reference/podcast.xml](reference/podcast.xml)

- [reference/rss-2.0-sample.xml](reference/rss-2.0-sample.xml)

- [reference/rss20.xml](reference/rss20.xml)

- [reference/scripting.rss](reference/scripting.rss)

### Snapshots

- [snapshots/podcast-feed.json](snapshots/podcast-feed.json)

- [snapshots/podcast-feed-rss.xml](snapshots/podcast-feed.xml)

- [snapshots/podcast-no-itunes-feed-rss.xml](snapshots/podcast-no-itunes-feed.xml)

- [snapshots/readme-feed.json](snapshots/readme-feed.json)

- [snapshots/readme-feed-rss.xml](snapshots/readme-feed.xml)

- [snapshots/extended-feed-rss.xml](snapshots/snapshot.xml)

- [snapshots/extended-feed.json](snapshots/test-feed.json)

## License

[MIT](https://tldrlegal.com/license/mit-license)

[0]: https://img.shields.io/badge/stability-experimental-orange.svg?style=flat-square

[1]: https://nodejs.org/api/documentation.html#documentation_stability_index

[2]: https://img.shields.io/npm/v/jsonfeed-to-rss.svg?style=flat-square

[3]: https://npmjs.org/package/jsonfeed-to-rss

[4]: https://github.com/bcomnes/jsonfeed-to-rss/actions/workflows/test.yml/badge.svg

[5]: https://github.com/bcomnes/jsonfeed-to-rss/actions/workflows/test.yml

[8]: http://img.shields.io/npm/dm/jsonfeed-to-rss.svg?style=flat-square

[9]: https://npmtrends.com/jsonfeed-to-atom

[10]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square

[11]: https://github.com/feross/standard

[12]: https://img.shields.io/coveralls/bcomnes/jsonfeed-to-rss/master.svg?style=flat-square

[13]: https://coveralls.io/github/bcomnes/jsonfeed-to-rss

[rss]: http://www.rssboard.org/rss-specification

[bp]: https://help.apple.com/itc/podcasts_connect/#/itc2b3780e76

[itunes]: https://help.apple.com/itc/podcasts_connect/#/itcb54353390

[categories]: https://help.apple.com/itc/podcasts_connect/?lang=en#/itc9267a2f12

[dc]: http://www.rssboard.org/rss-profile#namespace-elements-dublin-creator

[content]: http://web.resource.org/rss/1.0/modules/content/