From 9c08808c7fb9c19b4a1dd53926f97e5d0b8dcaf5 Mon Sep 17 00:00:00 2001 From: KongQun Yang Date: Fri, 10 Aug 2018 16:43:56 -0700 Subject: [PATCH] Add documentation for Ad Insertion Change-Id: Ia001a0a624c49854a31fd26008b2c7b3e81012f7 --- docs/source/documentation.rst | 5 +- docs/source/options/ads_options.rst | 14 +++++ docs/source/tutorials/ads.rst | 80 +++++++++++++++++++++++++++++ docs/source/tutorials/raw_key.rst | 2 +- docs/source/tutorials/widevine.rst | 2 +- 5 files changed, 100 insertions(+), 3 deletions(-) create mode 100644 docs/source/options/ads_options.rst create mode 100644 docs/source/tutorials/ads.rst diff --git a/docs/source/documentation.rst b/docs/source/documentation.rst index fb0845e53a..f007805151 100644 --- a/docs/source/documentation.rst +++ b/docs/source/documentation.rst @@ -40,7 +40,8 @@ Synopsis [MP4 Output Options] \ [encryption / decryption options] \ [DASH options] \ - [HLS options] + [HLS options] \ + [Ads options] .. include:: /options/stream_descriptors.rst @@ -54,6 +55,8 @@ Synopsis .. include:: /options/hls_options.rst +.. include:: /options/ads_options.rst + Encryption / decryption options ------------------------------- diff --git a/docs/source/options/ads_options.rst b/docs/source/options/ads_options.rst new file mode 100644 index 0000000000..7b31b98832 --- /dev/null +++ b/docs/source/options/ads_options.rst @@ -0,0 +1,14 @@ +Ads options +^^^^^^^^^^^ + +--ad_cues + + List of cuepoint markers separated by semicolon. The start_time represents + the start of the cue marker in seconds (double precision) relative to the + start of the program. This flag preconditions content for + `Dynamic Ad Insertion `_ with Google Ad Manager. + For DASH, multiple periods will be generated with period boundaries at the + next key frame to the designated start times; For HLS, segments will be + terminated at the next key frame to the designated start times and + '#EXT-X-PLACEMENT-OPPORTUNITY' tag will be inserted after the segment in + media playlist. diff --git a/docs/source/tutorials/ads.rst b/docs/source/tutorials/ads.rst new file mode 100644 index 0000000000..08805dfe9e --- /dev/null +++ b/docs/source/tutorials/ads.rst @@ -0,0 +1,80 @@ +Ad Insertion +============ + +Shaka Packager does not do Ad Insertion directly, but it can precondition +content for `Dynamic Ad Insertion `_ with Google Ad +Manager. + +Both DASH and HLS are supported. + +Synopsis +-------- + +:: + + $ packager ... \ + --ad_cues \ + [Other options, e.g. DRM options, DASH options, HLS options] + +Examples +-------- + +The examples below use the H264 streams created in :doc:`encoding`. + +Three midroll cue markers are inserted at 10 minutes, 30 minutes and 50 minutes +respectively. + +* DASH with live profile:: + + $ packager \ + 'in=h264_baseline_360p_600.mp4,stream=audio,init_segment=audio/init.mp4,segment_template=audio/$Number$.m4s' \ + 'in=input_text.vtt,stream=text,init_segment=text/init.mp4,segment_template=text/$Number$.m4s' \ + 'in=h264_baseline_360p_600.mp4,stream=video,init_segment=h264_360p/init.mp4,segment_template=h264_360p/$Number$.m4s' \ + 'in=h264_main_480p_1000.mp4,stream=video,init_segment=h264_480p/init.mp4,segment_template=h264_480p/$Number$.m4s' \ + 'in=h264_main_720p_3000.mp4,stream=video,init_segment=h264_720p/init.mp4,segment_template=h264_720p/$Number$.m4s' \ + 'in=h264_high_1080p_6000.mp4,stream=video,init_segment=h264_1080p/init.mp4,segment_template=h264_1080p/$Number$.m4s' \ + --ad_cues 600;1800;3000 \ + --generate_static_mpd --mpd_output h264.mpd + +* DASH with on-demand profile:: + + $ packager \ + in=h264_baseline_360p_600.mp4,stream=audio,output=audio.mp4 \ + in=input_text.vtt,stream=text,output=output_text.mp4 \ + in=h264_baseline_360p_600.mp4,stream=video,output=h264_360p.mp4 \ + in=h264_main_480p_1000.mp4,stream=video,output=h264_480p.mp4 \ + in=h264_main_720p_3000.mp4,stream=video,output=h264_720p.mp4 \ + in=h264_high_1080p_6000.mp4,stream=video,output=h264_1080p.mp4 \ + --ad_cues 600;1800;3000 \ + --mpd_output h264.mpd + +This generates six single-segment media files, one per stream, spanning multiple +periods. There may be problems handling this type of DASH contents in some +players, although it is recommended by `DASH IF IOP `_. +Use the below option if your player does not like it. + +* DASH with on-demand profile but one file per Period:: + + $ packager \ + 'in=h264_baseline_360p_600.mp4,stream=audio,output=audio_$Number$.mp4' \ + 'in=input_text.vtt,stream=text,output=output_text_$Number$.mp4' \ + 'in=h264_baseline_360p_600.mp4,stream=video,output=h264_360p_$Number$.mp4' \ + 'in=h264_main_480p_1000.mp4,stream=video,output=h264_480p_$Number$.mp4' \ + 'in=h264_main_720p_3000.mp4,stream=video,output=h264_720p_$Number$.mp4' \ + 'in=h264_high_1080p_6000.mp4,stream=video,output=h264_1080p_$Number$.mp4' \ + --ad_cues 600;1800;3000 \ + --mpd_output h264.mpd + +* HLS using transport streams:: + + $ packager \ + 'in=h264_baseline_360p_600.mp4,stream=audio,segment_template=audio_$Number$.aac' \ + 'in=input_text.vtt,stream=text,segment_template=output_text_$Number$.vtt' \ + 'in=h264_baseline_360p_600.mp4,stream=video,segment_template=h264_360p_$Number$.ts' \ + 'in=h264_main_480p_1000.mp4,stream=video,segment_template=h264_480p_$Number$.ts' \ + 'in=h264_main_720p_3000.mp4,stream=video,segment_template=h264_720p_$Number$.ts' \ + 'in=h264_high_1080p_6000.mp4,stream=video,segment_template=h264_1080p_$Number$.ts' \ + --ad_cues 600;1800;3000 \ + --hls_master_playlist_output h264_master.m3u8 + +.. include:: /options/ads_options.rst diff --git a/docs/source/tutorials/raw_key.rst b/docs/source/tutorials/raw_key.rst index 87808cf449..0ec8489ed8 100644 --- a/docs/source/tutorials/raw_key.rst +++ b/docs/source/tutorials/raw_key.rst @@ -24,7 +24,7 @@ Custom PSSH(s) can be provided in *--pssh*. If absent, Examples -------- -The examples below uses the H264 streams created in :doc:`encoding`. Here are +The examples below use the H264 streams created in :doc:`encoding`. Here are examples with DASH. It can be applied to HLS in a similar way. Common PSSH (one key for all streams):: diff --git a/docs/source/tutorials/widevine.rst b/docs/source/tutorials/widevine.rst index 63a9dfe0e7..d92cbe2ff8 100644 --- a/docs/source/tutorials/widevine.rst +++ b/docs/source/tutorials/widevine.rst @@ -35,7 +35,7 @@ RSA signing:: Examples -------- -The examples below uses the H264 streams created in :doc:`encoding`. +The examples below use the H264 streams created in :doc:`encoding`. * Here is an example with both DASH and HLS output::