epg/CONTRIBUTING.md

Contributing Guide

How do I add a program guide for the channel?

First, open the /sites folder and select the source that you know has the guide for the channel you want.

Then in the selected folder open the file *.channels.xml and add to it:

<channel lang="LANGUAGE_CODE" xmltv_id="CHANNEL_ID" site_id="SITE_ID">CHANNEL_NAME</channel>

Attribute	Description	Example
LANGUAGE_CODE	Language of the guide (ISO 639-1 code).	en
CHANNEL_ID	Channel ID from iptv-org/database. A complete list of supported channels can also be found at https://iptv-org.github.io/.	BBCOne.uk
SITE_ID	Unique ID of the channel used in the source.	bbc1
CHANNEL_NAME	Name of the channel used in the source.	BBC 1

After that just commit all changes and send a pull request.

How to add a new source to the repository?

To do this, you must create a new folder in the /sites with at least 3 files:

example.com.config.js

This file describes what kind of request we need to send to get the guide for a particular channel on a certain date. It also describes how to parse the response.

module.exports = {
	site: 'example.com',
	url: function ({ channel, date }) {
		return `https://example.com/api/${channel.site_id}/${date.format('YYYY-MM-DD')}`
	},
	parser: function ({ content }) {
		return JSON.parse(content)
	}
}

More detailed instructions for this file can be found here: https://github.com/freearhey/epg-grabber#site-config

example.com.test.js

With this file we can test the previously created config and make sure it works as you expect.

const { url, parser } = require('./example.com.config.js')
const dayjs = require('dayjs')
const utc = require('dayjs/plugin/utc')
dayjs.extend(utc)

const date = dayjs.utc('2022-11-18', 'YYYY-MM-DD').startOf('d')
const channel = { site_id: 'bbc1', xmltv_id: 'BBCOne.uk', lang: 'en' }

it('can generate valid url', () => {
	expect(url({ channel, date })).toBe('https://example.com/api/bbc1/2022-11-18')
})

it('can parse response', () => {
	const content = `[{"start":"2022-11-18T01:30:00.000Z","stop":"2022-11-18T02:00:00.000Z","title":"Program 1"}]`
	const results = parser({ content })

	expect(results).toMatchObject([
		{
			start: '2022-11-18T01:30:00.000Z',
			stop: '2022-11-18T02:00:00.000Z',
			title: 'Program 1'
		}
	])
})

it('can handle empty guide', () => {
	const results = parser({ content: '' })

	expect(results).toMatchObject([])
})

To run the tests you can use the following command:

npm test -- example.com

Detailed documentation for the tests can be found here: https://jestjs.io/docs/using-matchers

example.com.channels.xml

This file contains a list of channels available at the source.

<?xml version="1.0" encoding="UTF-8" ?>
<site site="example.com">
 <channels>
   <channel lang="en" xmltv_id="BBCOne.uk" site_id="bbc1">BBC 1</channel>
 </channels>
</site>

After creating all the files we can make sure that the guide loads correctly and has no errors using the command:

npx epg-grabber --config=sites/example.com/example.com.config.js --channels=sites/example.com/example.com.channels.xml --output=guide.xml --days=2

If the download is successful, the guide.xml file with the ready to use program should appear in the root directory.

After that, all that remains is to commit all the changes and send a pull request.