********************
youtube
********************

Requires an Egeria identity of type ``google`` to work. Set it up with:

>>> egeriactl auth google <id> <secret>

Configuration
=============

================    ======= ===========
Option              Type    Description
================    ======= ===========
mode                String  Mandatory. Choose between "subscriptions" (monitor your subs), "playlists" (monitor one or more playlists), "search" (monitor the results of one or more searches), "channels" (monitor one or more channels).
limit               Integer Mandatory. How many videos to fetch from each subscribed channel or playlist or search result or channel.
ids                 Array   Mandatory for all modes except "subscriptions". Must be one or more playlist ids or search terms or channel names
sort                String  Defaults to 'date'; can be 'relevance'. Decide if you want the latest videos first, or the most relevant.
identity            String  Mandatory. Must be an Egeria identity of type "google".
================    ======= ===========

Upstream API docs
=================

`Yotube Data API v3 <https://developers.google.com/youtube/v3/docs/>`__

Output: ``subscriptions``, ``channels`` and ``search`` mode
===========================================================

======================================  ======  ============    ===================
Field                                   Type    Notes           Description / Value
======================================  ======  ============    ===================
youtube:channel:publishedAt             Date                    When the channel was created
youtube:channel:title                   String
youtube:channel:description             String
youtube:channel:thumbnails:default:url  URL     Full address
youtube:channel:thumbnails:medium:url   URL     Full address
youtube:channel:thumbnails:high:url     URL     Full address
youtube:video:id                        String                  Unique video ID, part of the video's page URL
youtube:video:publishedAt               Date                    When the video was uploaded to the channel
youtube:video:title                     String
youtube:video:description               String
youtube:video:thumbnails:default:url    URL     Full address
youtube:video:thumbnails:medium:url     URL     Full address
youtube:video:thumbnails:high:url       URL     Full address
youtube:video:link                      URL     Full address    Link to the video page
======================================  ======  ============    ===================

Output: ``playlists`` mode
==========================

Everything present in the output of the other modes, plus:

=========================================== ======  ============    ===================
Field                                       Type    Notes           Description / Value
=========================================== ======  ============    ===================
youtube:playlist:publishedAt                Date                    When the playlist was created
youtube:playlist:title                      String
youtube:playlist:description                String
youtube:playlist:thumbnails:default:url     URL     Full address
youtube:playlist:thumbnails:medium:url      URL     Full address
youtube:playlist:thumbnails:high:url        URL     Full address
youtube:playlist:thumbnails:standard:url    URL     Full address
youtube:playlist:thumbnails:maxres:url      URL     Full address
=========================================== ======  ============    ===================

Examples
========

Fetch 4 videos from each subscribed channel every 12 hours:

.. code-block:: javascript

    "tasks": [{
        "name": "test",
        "chain": [{
            "plugin": "youtube",
            "configuration": {
                "identity": "gglMyName",
                "mode": "subscriptions",
                "limit": 4,
                "plan": "0 */12 * * *"
            }
        }, {
            "plugin": "inspect"
        }]
    }]

Monitor two playlists, fetching 4 videos from each one every 24 hours at midnight:

.. code-block:: javascript

    "tasks": [{
        "name": "test",
        "chain": [{
            "plugin": "youtube",
            "configuration": {
                "identity": "gglMyName",
                "mode": "playlists",
                "ids": [
                    "PLAbMhAYRuCUhawCEV2oXZGrienoKTN16X",
                    "PLFPEDTXyQKoPZvHSBdoRLJAlUqdWVVgYT"
                ],
                "limit": 4,
                "plan": "0 0 * * *"
            }
        }, {
            "plugin": "inspect"
        }]
    }]

Every day at midgnight get the 6 most relevant results of searching for "DOOM trailer":

.. code-block:: javascript

    "tasks": [{
        "name": "test",
        "chain": [{
            "plugin": "youtube",
            "configuration": {
                "identity": "gglMyName",
                "mode": "search",
                "ids": ["DOOM trailer"],
                "limit": 6,
                "sort": "relevance",
                "plan": "0 0 * * *"
            }
        }, {
            "plugin": "inspect"
        }]
    }]