epg/CONTRIBUTING.md

Contributing Guide

• How to?
• Project Structure
• Scripts

How to?

How to add a channel to the guide?

First, select a site from the SITES.md that you know has a guide for the channel you need. Then go to the folder with its config and open the file *.channels.xml.

Check the channel list and make sure that the channel you want is in it and that it has the correct xmltv_id. The full list of supported channels and their IDs can be found at iptv-org.github.io. If the channel is not in our database yet, you can add it to it through this form.

If the desired channel is not in *.channels.xml, just add a new line with its description to it:

<?xml version="1.0" encoding="UTF-8"?>
<channels>
  ...
  <channel site="SITE" lang="LANGUAGE_CODE" xmltv_id="CHANNEL_ID" site_id="SITE_ID">CHANNEL_NAME</channel>
  ...
</channels>

Attribute	Description	Example
SITE	Site domain name.	example.com
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 One

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

How to map the channels?

In order for the guides to be linked with playlists from iptv-org/iptv and also with our other projects, each channel must have the same ID in the description as in our iptv-org/database.

To check this, select one of the sites in the SITES.md, open its *.channels.xml file and check that all channels have a valid xmltv_id. If it is missing somewhere, just copy the matching ID from the iptv-org.github.io. If the channel is not in our database yet, you can add it to it through this form.

If the *.channels.xml file contains many channels without xmltv_id, you can speed up the process by running the command in the Console (or Terminal if you have macOS):

npm run channels:edit path/to/channels.xml

This way, you can map channels by simply selecting the proper ID from the list:

? Select xmltv_id for "BBC One" (bbc1): (Use arrow keys)
❯ BBC One (BBC1, BBC Television, BBC Television Service) | BBCOne.uk
  BBC One HD | BBCOneHD.uk
  Type...
  Skip

Once complete, commit all changes and send a pull request.

How to add a new source to the repository?

To do this, you will need to create a new folder in the /sites directory with at least 4 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 and how to parse the response.

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

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 { parser, url } = require('./example.com.config.js')
const dayjs = require('dayjs')
const utc = require('dayjs/plugin/utc')
const customParseFormat = require('dayjs/plugin/customParseFormat')
dayjs.extend(customParseFormat)
dayjs.extend(utc)

const date = dayjs.utc('2025-01-12', 'YYYY-MM-DD').startOf('d')
const channel = { site_id: 'bbc1', xmltv_id: 'BBCOne.uk' }

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

it('can parse response', () => {
  const content =
    '[{"title":"Program 1","start":"2025-01-12T00:00:00.000Z","stop":"2025-01-12T00:30:00.000Z"},{"title":"Program 2","start":"2025-01-12T00:30:00.000Z","stop":"2025-01-12T01:00:00.000Z"}]'

  const results = parser({ content })

  expect(results.length).toBe(2)
  expect(results[0]).toMatchObject({
    title: 'Program 1',
    start: '2025-01-12T00:00:00.000Z',
    stop: '2025-01-12T00:30:00.000Z'
  })
  expect(results[1]).toMatchObject({
    title: 'Program 2',
    start: '2025-01-12T00:30:00.000Z',
    stop: '2025-01-12T01:00:00.000Z'
  })
})

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

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

To run all of these tests 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" ?>
<channels>
  <channel site="example.com" lang="en" xmltv_id="BBCOne.uk" site_id="bbc1">BBC One</channel>
</channels>

readme.md

This file contains instructions on how to use this config.

# example.com

https://example.com

### Download the guide

```sh
npm run grab --- --site=example.com
```

### Test

```sh
npm test --- example.com
```

The fastest way to create all these files is to use the command:

npm run sites:init --- example.com

Once you are done working on the config make sure the tests pass, the guide downloads correctly, commit all changes and send us a pull request.

Project Structure

• .github/
  • ISSUE_TEMPLATE/: issue templates for the repository.
  • workflows: contains GitHub actions workflows.
  • CODE_OF_CONDUCT.md: rules you shouldn't break if you don't want to get banned.
• scripts/: contains all scripts used in the repository.
• sites/: contains configurations, channel lists and tests for all sites.
• tests/: contains tests to check the scripts.
• CONTRIBUTING.md: file you are currently reading.
• README.md: project description displayed on the home page.
• SITES.md: list of all supported sites and their current status.

Scripts

These scripts are created to automate routine processes in the repository and make it a bit easier to maintain.

For scripts to work, you must have Node.js installed on your computer.

To run scripts use the npm run <script-name> command.

• act:check: allows to test the check workflow locally. Depends on nektos/act.
• act:update: allows to test the update workflow locally. Depends on nektos/act.
• api:load: downloads the latest channels data from the iptv-org/api.
• api:generate: generates a JSON file with all channels for the iptv-org/api repository.
• channels:lint: сhecks the channel lists for syntax errors.
• channels:parse: generates a list of channels based on the site configuration.
• channels:edit: utility for quick channels mapping.
• channels:validate: checks the description of channels for errors.
• sites:init: creates a new site config from the template.
• sites:update: updates the list of sites and their status in SITES.md.
• grab: downloads a program from a specified source.
• serve: starts the web server.
• lint: сhecks the scripts for syntax errors.
• test: runs a test of all the scripts described above.