This page describes step by step how to configure the AVTool to upload video files to YouTube. For a full reference, see AVTool Guide.
Prerequisites
You need:
- A document type in Sophora that references video files and its metadata. The metadata may be augmented by a script that uses other documents as additional source (like a broadcast or asset document).
- A binary video file that YouTube supports. Select a video format that best fits your needs.
- A YouTube channel. You need the credentials to access the YouTube API. See section "Authentication (OAuth)" below.
1. Document type and servers
See media configuration for configuring the node type and the media server.
2. Global YouTube configuration
Properties shared by all the videos and all the YouTube channels can be set in the mediaconfig.xml as "youtubeGlobalConfig".
The most important setting is the "youtubeAccountPropertyName". It determines which property in the video document will specify the YouTube channel, to which the video should be uploaded. In the video document, the value of this property must be the ID of a channel configuration.
<!-- YouTube settings for all channels -->
<bean id="youtubeGlobalConfig" class="com.subshell.sophora.avtool.api.youtube.YoutubeConfiguration">
<!-- Property of the document that indicates which channel to use. -->
<property name="youtubeAccountPropertyName" value="example:youtubeChannel" />
<!-- The YouTube action to take when a video document is deleted or set offline. Options are DELETE, SET_PRIVATE, and DO_NOTHING. -->
<property name="deleteEventAction" value="DELETE" />
<property name="offlineEventAction" value="SET_PRIVATE" />
<!-- Application for adding opener and closer to the beginning/end of video. The specific videos are configured per channel. -->
<property name="concatVideosScript"
value="/cms-install-directory/ytc_opener_und_closer/addOpenerCloser_ffmpeg.sh" />
</bean>
3. YouTube channel configuration
Each YouTube channel that you want to upload videos to must be configured beforehand. The configuration is best done in Sophora as a system document in the administration area, but it can also be defined in the mediaconfig.xml as a Spring bean.
For the "Video format", enter the same as in the first step, i.e. "youtube" and make sure that a child node of the video has that format (normally done via a pre-processor script).
YouTube Channel Configuration in the Sophora DeskClient
The YouTube Channels are configured directly in the Sophora Admin View, using the document type "YouTube Channel" (sophora-extension-nt:youtubeChannelConfiguration). This document type is created by the AVTool when it connects to the Sophora Primary Server for the first time. The creation of the document type is only possible if the AVTool user has the required permssions.
Each YouTube channel configuration document has an ID (property sophora-extension:id). In each video, there must be a property referencing the ID of a YouTube channel document. The name of this property is defined by the property youtubeAccountPropertyName in the global YouTube configuration in the mediaconfig.xml. If this property is not set in a video document, it will not be uploaded to YouTube.
- Both the Teaser image of the video and the overlay image should be as large as possible, as the generated thumbnail image will also be used as the preview image in the embedded YouTube video player. The combined size of both images should not exceed 2 MB in total due to upload limitations on YouTube.
- Preferably, the images should follow a 16:9 aspect ratio.
- The overlay image should contain transparency and be in one of the supported image formats (.GIF or .PNG). It should also have the same dimensions as the Teaser image. For this reason, it is recommended to use a custom image variant for both images that complies with the abovementioned suggestions instead of the "original" image variant.
For further recommendations, please check the best practices from YouTube.
The Video Data Section
The properties in the "Video Data" section of the channel configuration define the metadata for each video that is uploaded to YouTube. Every field can either reference a property in the video document, a groovy script, or contain plain string content.
- If the property value matches the regular expression given by the property
tagging.scriptClassPrefix.regexpin the application.properties, it references a Groovy tagging script. See Tagging Script. - If the property value matches the regular expression given by the property
tagging.propertyPrefix.regexpin the application.properties, it is assumed to be the name of a property in the video document. - If neither regular expression matches, the value is used as-is for all videos.
YouTube Content Partner
If you are a YouTube Content partner and want to use the YouTube Content ID API to claim your videos and apply policies, you need to specify a content owner. An additional authorization is also necessary. You have two options for authenticating:
- Accessing the YouTube Data API and YouTube Content ID API with different accounts.
- Accessing the YouTube Data API and the YouTube Content ID API with a single account.
In the second case, a YouTube CMS user is used to access both APIs. The given content owner is also used for the YouTube Data API to act on behalf of YouTube CMS user. If the CMS user has access to multiple channels, you need to configure the channel ID, so that the uploaded videos are assigned to that channel. For authentication, you need to provide a "Client ID" and a "Client secret" of a client that has access to both APIs (no service account is used).
Intro and Outro Videos
Prior to the upload process, an additional tool may concatenate intro or outro videos to the main video. The tool must be specified by the property concatVideosScript in the global YouTube configuration in the mediaconfig.xml. A general intro and outro video for a YouTube channel can be defined in the channel configuration, where the paths to the local files of the intro and outro can be set (both are optional).
It is also possible to select different intro/outro videos for the uploaded video, which will be used instead of the ones specified in the channel configuration. To enable this feature, it is necessary to create and publish documents of type "YouTube Packaging". They define a pair of an intro and an outro video, and can be given a recognizable name.
To use the "YouTube Packaging" documents, the mixin sophora-extension-mix:introOutroSet with the property sophora-extension:introOutroSet is provided. The mixin and the property must be added to the configuration of the video document type. Afterwards, you are able to select a "YouTube Packaging" for a specific YouTube video in the document editor. Note that after uploading a video for the first time to YouTube, the file will not be updated anymore and therefore further changes to the packaging are not possible.
The referenced video documents must have the same document type that is configured in the AVTool (with a
MediaDocumentDescription in the mediaconfig.xml). The files must be accessible at the media server in the same manner as the videos to upload to YouTube. You can restrict the type of documents to use as intro/outro video in the default property configuration of sophora-extension:introDocument/sophora-extension:outroDocument or in the node type configuration of sophora-extension-nt:introOutroSet.Authentication (OAuth)
The AVTool uses the OAuth 2.0 flow for web server applications for authentication against the YouTube Data API v3.
Visit the tab "YouTube authorization" in the channel document or the URL http://myavtool.example.com:5063/api/oauth2/start/youtube?channelId=<ID of YouTube Channel in Sophora> using your browser. After you have accepted the access permissions requested by the AVTool, the browser will send an authentication code to the AVTool. The AVTool will now use the auth code to generate credentials for YouTube. If successful, the corresponding message is displayed. The credentials are saved in the directory "~/.oauth-credentials".
- Follow the steps for obtaining authorization credentials to register the AVTool with YouTube. Make sure to select the correct project at the top of the cloud console. Create an OAuth client ID of type "Web application" and give it a name. You must set "Authorized redirect URIs" to point to your installed AVTool. You can get this URL from the AVTool itself if you visit
http://myavtool.example.com:5063/api/oauth2/redirecturiin your browser. Replace the servername and port if you changed it. Else use the following URL where you need to adapt the hostname and maybe port:http://myavtool.example.com:5063/api/oauth2/end/youtube. This URL must be reachable from the browser of the authenticating user, but it does not need to be reachable from the internet. - When you are done, copy the "Client ID" and "Client secret" to the YouTube channel configuration document in Sophora and publish it.
