delarte

🎬 ArteTV downloader

💡 What is it ?

This is a toy/research project whose primary goal is to familiarize with some of the technologies involved in multi-lingual video streaming. Using this program may violate usage policy of ArteTV website and we do not recommend using it for other purpose then studying the code.

ArteTV is a is a European public service channel dedicated to culture. Programmes are usually available with multiple audio and subtitles languages.

🚀 Quick start

Install FFMPEG binaries and ensure it is in your PATH

$ ffmpeg -version
ffmpeg version N-109344-g1bebcd43e1-20221202 Copyright (c) 2000-2022 the FFmpeg developers
built with gcc 12.2.0 (crosstool-NG 1.25.0.90_cf9beb1)

Clone this repository

$ git clone https://git.afpy.org/fcode/delarte.git
$ cd delarte

Optionally create a virtual environnement

$ python3 -m venv .venv
$ source .venv/Scripts/activate

Install in edit mode

$ pip install -e .

Or install in edit mode with dev dependencies if you intend to contribute.

$ pip install -e .[dev]

Now you can run the script

$ python3 -m delarte --help
or
$ delarte --help
delarte - ArteTV downloader.

Usage:
  delarte (-h | --help)
  delarte --version
  delarte [options] URL
  delarte [options] URL RENDITION
  delarte [options] URL RENDITION VARIANT

Download a video from ArteTV streaming service. Omit RENDITION and/or
VARIANT to print the list of available values.

Arguments:
  URL         the URL from ArteTV website
  RENDITION   the rendition code [audio/subtitles language combination]
  VARIANT     the variant code [video quality version]

Options:
  -h --help   print this message
  --version   print current version of the program
  --debug     on error, print debugging information

🔧 How it works

🏗️ The streaming infrastructure

Every video program have a program identifier visible in their web page URL:

https://www.arte.tv/es/videos/110139-000-A/fromental-halevy-la-tempesta/
https://www.arte.tv/fr/videos/100204-001-A/esprit-d-hiver-1-3/
https://www.arte.tv/en/videos/104001-000-A/clint-eastwood/

That program identifier enables us to query an API for the program's information.

The config API

For the last example the API call is as such:

https://api.arte.tv/api/player/v2/config/en/104001-000-A

The response is a JSON object, a sample of which can be found here:

Information about the program is detailed in $.data.attributes.metadata and a list of available audio/subtitles combinations in $.data.attributes.streams. In our code such a combination is referred to as a rendition (or version in the CLI).

Every such rendition has a reference to a master playlist file in .streams[i].url

The master playlist file

As defined in HTTP Live Streaming (sample file can be found here or here). This file show the a list of video variants URIs (one per video resolution). Each of them has

• exactly one video media playlist reference
• exactly one audio media playlist reference
• at most one subtitles media playlist reference

Audio and subtitles tracks reference also include:

• a two-letter language code attribute (mul is used for audio multiple language)
• a free form name attribute that is used to detect an audio original version
• a coded characteristics that is used to detect accessibility tracks (audio or textual description)

The video and audio media playlist file

As defined in HTTP Live Streaming (a sample file can be found here or here). This file is basically a list of segments (http ranges) the client is supposed to download in sequence.

The subtitles media playlist file

As defined in HTTP Live Streaming (a sample file can be found here). This file references the actual file containing the subtitles VTT data.

⚙️The process

1. Figure out available sources by:

   • fetching the config API object for the program identifier
   • fetching all referenced master playlist.

2. Select the desired source based on renditions and variants codes.

3. Figure out the output filename from source details.

4. Download video, audio and subtitles media content.

   • convert VTT subtitles to SRT

5. Feed the all the media to ffmpeg for multiplexing (or muxing)

📽️ FFMPEG

The multiplexing (muxing) the video file is handled by ffmpeg. The script expects ffmpeg to be installed in the environnement and will call it as a subprocess.

Why not use FFMPEG directly with the HLS master playlist URL ?

So we can be more granular about renditions and variants that we want.

Why not use VTT subtitles directly ?

Because FFMPEG do not support styles in WebVTT 😒.

Why not use FFMPEG directly with the media playlist URLs and let it do the download ?

Because some programs would randomly fail 😒. Probably due to invalid segmentation on the server.

📌 Dependencies

• m3u8 to parse playlists.
• requests to handle HTTP traffic.
• docopt-ng to parse command line.

🤝 Help

For sure ! The more the merrier.