summaryrefslogtreecommitdiff
path: root/obsolete/macros/latex/contrib/yt4pdf/doc/yt4pdf_man.tex
blob: 97febc04f1a1769d8a552e739a20a2c54d3da68c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
% makeindex < aebpro_man.idx > aebpro_man.ind
\documentclass{article}
\usepackage[fleqn]{amsmath}
\usepackage[
    web={centertitlepage,designv,tight*,usetemplates,
        forcolorpaper,latextoc,pro},%usesf,
        eforms,aebxmp
]{aeb_pro}
%\usepackage{multicol}
\usepackage{aeb_mlink}
\usepackage{array}
\usepackage[altbullet]{lucidbry}

\usepackage{makeidx}
\makeindex
\usepackage{acroman}

\usepackage[active]{srcltx}

\def\expath{../examples}

\urlstyle{rm}
\def\pkg{\textsf}
\let\app\textsf
\let\opt\texttt
\let\uif\textsf
\let\env\texttt
\def\meta#1{\textit{\texttt{#1}}}
\def\ameta#1{$\langle\textit{\texttt{#1}}\rangle$}
\newdimen\aebdimen \aebdimen6pt %\partopsep  \advance\aebdimen\partopsep
\newcommand\bVerb[1][]{\begingroup#1\vskip\aebdimen\parindent0pt}%
\def\eVerb{\vskip\aebdimen\endgroup\noindent}
\def\SUB#1{\ensuremath{{}_{\text{#1}}}}
\def\darg#1{\texttt{\{#1\}}}
\def\takeMeasure{\bgroup\obeyspaces\takeMeasurei}
\def\takeMeasurei#1{\global\setbox\webtempboxi\hbox{\ttfamily#1}\egroup}
\def\bxSize{\wd\webtempboxi+2\fboxsep+2\fboxrule}
\let\amtIndent\leftmargini
\makeatletter
\def\setDisplayNumber#1#2{\kern0pt
    \setlength\abovedisplayshortskip{0pt}%
    \setlength\belowdisplayshortskip{0pt}%
    \setlength\abovedisplayskip{0pt}%
    \setlength\belowdisplayskip{0pt}%
    \begin{equation}\label{#2}\end{equation}\kern0pt
}
\renewenvironment{quote}[1][]
   {\def\@rgi{#1}\ifx\@rgi\@empty
    \let\rghtm\@empty\else\def\rghtm{\rightmargin\leftmargin}\fi
    \list{}{\rghtm} %{\rightmargin\leftmargin}%
    \item\relax}
   {\endlist}
\renewcommand*\descriptionlabel[1]{\hspace\labelsep
    \normalfont #1}
\setcounter{secnumdepth}{4}
\setcounter{tocdepth}{5}
\renewcommand*{\theparagraph}{\texorpdfstring{\protect\P\protect\ }{\textparagraph}}
\renewcommand{\paragraph}
    {\renewcommand{\@seccntformat}[1]{\theparagraph}%
    \@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\color{\aeb@subsubsectioncolor}\bfseries}}
\renewcommand*\l@paragraph{\@dottedtocline{4}{5.0em}{1em}} %{7.0em}{4.1em}}
\def\chgCurrLblName#1{\def\@currentlabelname{#1}}
\def\echgCurrLblName#1{\edef\@currentlabelname{#1}}
\makeatother


\newcommand{\YouTube}{\textsf{YouTube}}


%\def\tutpath{doc/tutorial}
%\def\tutpathi{tutorial}

\DeclareDocInfo
{
    university={\AcroTeX.Net},
    title={The \texorpdfstring{\textsf{yt4PDF} Package\\[1em]}{: }
        Playing \texorpdfstring{\YouTube}{YouTube} Videos in PDF},
    author={D. P. Story},
    email={dpstory@acrotex.net},
    subject={Playing YouTube Videos in PDF},
    talksite={\url{www.acrotex.net}},
    version={1.1, 2016/10/04},
    keywords={AcroTeX, PDF, YouTube, rmannot},
    copyrightStatus=True,
    copyrightNotice={Copyright (C) \the\year, D. P. Story},
    copyrightInfoURL={http://www.acrotex.net}
}

\def\dps{$\hbox{$\mathfrak D$\kern-.3em\hbox{$\mathfrak P$}%
   \kern-.6em \hbox{$\mathcal S$}}$}

\universityLayout{fontsize=Large}
\titleLayout{fontsize=LARGE}
\authorLayout{fontsize=Large}
\tocLayout{fontsize=Large,color=aeb}
\sectionLayout{indent=-40pt,fontsize=large,color=aeb} %,afterskip=1sp}
\subsectionLayout{indent=-20pt,color=aeb} %,afterskip=1sp}
\subsubsectionLayout{indent=0pt,color=aeb} %,afterskip=1sp}
\subsubDefaultDing{\texorpdfstring{$\bullet$}{\textrm\textbullet}}

\newenvironment{eqComments}[1][\strut]{\smallskip\leftskip-\labelwidth
\item[]\textbf{\textcolor{blue}{#1}}}{\par\smallskip}

%\pagestyle{empty}
%\parindent0pt\parskip\medskipamount

\chngDocObjectTo{\newDO}{doc}
\begin{docassembly}
var titleOfManual="The yt4pdf MANUAL";
var manualfilename="Manual_BG_Print_yt4pdf.pdf";
var manualtemplate="Manual_BG_Brown.pdf"; // Blue, Green, Brown
var _pathToBlank="C:/Users/Public/Documents/ManualBGs/"+manualtemplate;
var doc;
var buildIt=false;
if ( buildIt ) {
    console.println("Creating new " + manualfilename + " file.");
    doc = \appopenDoc({cPath: _pathToBlank, bHidden: true});
    var _path=this.path;
    var pos=_path.lastIndexOf("/");
    _path=_path.substring(0,pos)+"/"+manualfilename;
    \docSaveAs\newDO ({ cPath: _path });
    doc.closeDoc();
    doc = \appopenDoc({cPath: manualfilename, oDoc:this, bHidden: true});
    f=doc.getField("ManualTitle");
    f.value=titleOfManual;
    doc.flattenPages();
    \docSaveAs\newDO({ cPath: manualfilename });
    doc.closeDoc();
} else {
    console.println("Using the current "+manualfilename+" file.");
}
var _path=this.path;
var pos=_path.lastIndexOf("/");
_path=_path.substring(0,pos)+"/"+manualfilename;
\addWatermarkFromFile({
    bOnTop:false,
    bOnPrint:false,
    cDIPath:_path
});
\executeSave();
\end{docassembly}

\begin{document}

\maketitle

\selectColors{linkColor=black}
\tableofcontents
\selectColors{linkColor=webgreen}

\section{Introduction}\label{s:intro}

 I believe that I was vaguely aware of the \href{http://code.google.com/apis/youtube/flash_api_reference.html}
{{\YouTube} ActionScript 3.0 Player},\footnote{The YouTube AcrionScript 2.0 Player API
 has been deprecated as of January 27, 2015; however, it is still supported, for now.} but never pursued it because of my
general lack of interest in {\YouTube} (\url{www.youtube.com}). Recently, I
came across a very nice demo PDF that used the API, see
%\mlhref{http://www.uvsar.com/pdftube/}{PDF Tube - {\YouTube} API wrapper for PDF documents}.
``PDF Tube - {\YouTube} API wrapper for PDF documents'' (the page has
since been removed).
The SWF file and JavaScript are made freely available, so I
downloaded it, and was sufficiently impressed to port the example to
{\LaTeX} using various members of the {Acro\negthinspace\TeX} Fine Family of Software
\verb!:-{)!. The SWF file and JavaScript are due to the good folks at
\textbf{UVSAR} (\url{www.uvsar.com}). The \textbf{UVSAR}'s sample demo also appeared in the forums of
the \href{http://acrobatusers.com/forum/javascript/embed-youtube-video-pdf}{Acrobat User
Community}.

The \textsf{yt4pdf} package uses the \textsf{rmannot} to embed the \textsf{SWF}
file that plays the {\YouTube} videos.  There is a complete set of buttons
that come with the package to control the video: play, pause, stop
loading, rewind, load a video by its {\YouTube} video ID, and a button to
view a video on the {\YouTube} web site.\footnote{Some videos do not allow
embedded playback, and must be viewed on the {\YouTube} web site.}

% http://acrobatusers.com/news/youtube-widget-acrobat

\subsection{Sample files}

The following are the sample files shipped with \textsf{yt4pdf}:
\begin{itemize}
    \item \texttt{yt4pdf-1.tex} demonstrates the basic functionality of
    the {\YouTube} RMA: the use of the poster, including \cs{ytComboList},
    \cs{ytComboBtn}, and \cs{ytvId}.
    \item \texttt{yt4pdf-2.tex} experiments with different ways the
    {\YouTube} annotation can be displayed
    \begin{itemize}
        \item As a small icon, videos are played in a floating window,
        buttons displayed in the running footer.
        \item[] This one uses a rollover, popup menu system (as opposed to
        a combo box). The \textsf{popupmenu} package is used.
        \item Using a built-in poster, with the combo box under the
        annotation, control buttons in running footer.
        \item Same as above, but control buttons moved to a two column
        format.
        \item Using the custom {\YouTube} for PDF poster with combo box and
        control buttons under the RMA.
    \end{itemize}
    \item \texttt{yt4pdf-3.tex} illustrates the usage of the \texttt{play} and \texttt{load}
    keys that are passed in the optional parameter of \cs{ytRmAnnot}.
\end{itemize}
% Advanced examples \href{http://www.math.uakron.edu/~dpstory/aebblog.html}{AeB Blog site}.

\section{Requirements}

This package is part of \textsf{AeB Pro}, which means Acrobat Distiller is
used to create the PDF; the package requires \textsf{rmannot}, which
creates rich media annotations. Therefore, we require
\begin{equation*}
    \boxed{\text{\large\bfseries Adobe Acrobat, version 9.0 or later}}
\end{equation*}
To use this package, the document author must have AeB and AeB Pro
installed, as well as \textsf{rmannot}. The manual for \textsf{rmannot}
needs to be read closely to properly install it and to function correctly.
I have made \textsf{rmannot} a required package, and recently
have made the \textsf{popupmenu} package required as well.

\section{Configuring your installation}

In addition to configuring the \textsf{rmannot} package correctly, the
\textsf{yt4pdf} package needs configuring as well. The \textsf{yt4pdf} package
comes with a configuration file \texttt{yt4pdf.cfg}.  Open this file in
your favorite editor to see
\begin{Verbatim}[fontsize=\small]
% yt4pdf config file. Delete the \endinput below and replace the path
% provided with the path to the swf folder of your yt4pdf installation.
% This path is used to locate the pdf_tube_basic.swf file, used to play
% YouTube videos.
\endinput
\renewcommand{\ytFolder}{C:/Users/Public/Documents/My TeX Files/%
tex/latex/aeb/aebpro/yt4pdf/swf}
\end{Verbatim}
Edit this file so that \cs{ytFolder} points to the \texttt{swf} folder on
your computer.

\section{The Rich Mediation Annotation for {\YouTube}}

The Rich Media Annotation (RMA) used is \cs{ytRmAnnot}, its definition
uses the command \cs{rmAnnot}, which is defined in the \textsf{rmannot} package.
\bVerb\takeMeasure{\string\ytRmAnnot[\ameta{KV-pairs}]\darg{\ameta{name}}\darg{\ameta{width}}\darg{\ameta{height}}}%
\begin{minipage}{\linewidth}
\begin{minipage}{\bxSize}
\xdef\panelWidth{\the\linewidth}%
\begin{Verbatim}[frame=single,commandchars=!(),rulecolor=\color{red}]
\ytRmAnnot[!ameta(KV-pairs)]{!ameta(name)}{!ameta(width)}{!ameta(height)}
\end{Verbatim}
\end{minipage}\hfill
\begin{minipage}{\linewidth-\panelWidth}
\setDisplayNumber\label{display:ytRmAnnot}
\end{minipage}\end{minipage}\endgroup
\PD
\begin{enumerate}
    \item The first (optional) parameter is used to pass the key-value pairs of the
    \cs{rmAnnot} command. Additionally, there are two other \ameta{KV-pairs}
    recognized, specialized to the \cs{ytRmAnnot} command.
    \begin{itemize}
        \item \texttt{play=\ameta{vID}} Loads and plays the {\YouTube} video with
            video ID of \ameta{vID}.
        \item \texttt{load=\ameta{vID}} Loads the specified video's thumbnail
            (as specified by \ameta{vID}) and prepares the player to play
            the video. The player does not request the \textsf{FLV} until the play
            button is pressed.
    \end{itemize}
    When you want to play a {\YouTube} video when the page containing
    the annotation is opened, use the \texttt{play} key; for example
    \texttt{play=GZ9e3Dy7obA} causes the video whose video ID is
    \texttt{GZ9e3Dy7obA} to play when the page is opened.

    See the manual for the \pkg{rmannot} package for more details on the
    key-value pairs that can be passed through the optional first
    parameter.

    \item The \ameta{name} parameter is a name used to refer to the
    annotation through underlying JavaScript code. The \ameta{name}
    should consist of only letters and numbers. The value of this
    parameter is placed in the macro \cs{ytCurrRMAName}. This macro is
    used internally by the various control buttons.

    \item The width of the annotation.

    \item The height of the annotation.
\end{enumerate}

\paragraph*{Annot Dimensions.}
The width and height of the {\YouTube} annotation should be \texttt{571bp}
and \texttt{330bp}, respectively, or any re-scaling of these dimensions.

Examples,
\begin{Verbatim}
    \ytRmAnnot[posternote=AcroTeX PDF Tube,play=eNzrn8-JFSE,
        deactivated=pageclose]{YouTube1}{571bp}{330bp}
\end{Verbatim}
is a ``full-size'' annotation, while
\begin{Verbatim}
    \ytRmAnnot[posternote=AcroTeX PDF Tube,load=eNzrn8-JFSE,
        deactivated=pageclose]{YouTube1}{571bp/2}{330bp/2}
\end{Verbatim}
is half that size. The first example above plays a video when
the page is opened, the second example loads the thumbnail, and waits play
the video.

You can also re-scale using either \cs{resizebox} or
\cs{scalebox} from the \textsf{graphicx} package.
\begin{Verbatim}
    \resizebox{2in}{!}{\ytRmAnnot[posternote=AcroTeX PDF Tube,
        deactivated=pageclose]{YouTube1}{571bp}{330bp}}
\end{Verbatim}
or, using \cs{scalebox},
\begin{Verbatim}
    \scalebox{.5}{\ytRmAnnot[posternote=AcroTeX PDF Tube,
        deactivated=pageclose]{YouTube1}{571bp}{330bp}}
\end{Verbatim}

\textbf{Running multiple videos at once.} At the time of this writing, the
\pkg{yt4pdf} package is not designed to run more than one video at a
time, that's not saying it cannot be done, however. It is not recommended,
indeed, why would you want to look at two {\YouTube} videos at the same
time?

For documents with multiple {\YouTube} annotations over
several pages it is recommended, therefore, that the \texttt{deactivated=pageclose}
should be used in the optional parameter list of the \cs{ytRmAnnot}
command.

\subsection{The \texorpdfstring{\protect\textsf{yt4pdf}}{yt4pdf} Poster}

The \textsf{rmannot} package provides a standard poster (a gray rectangle
with text in the lower left corner). However, there is an especially
designed poster, designed by the folks at \textbf{UVSAR}. (See
Figure~\ref*{pdfytPoster}, page~\pageref*{pdfytPoster}.)

\begin{figure}[htb]
\begin{center}
    \includegraphics[scale=.5]{./graphics/pdfyt_poster}\\
    \caption{YouTube for PDF poster}\label{pdfytPoster}
\end{center}
\end{figure}

\goodbreak
\textbf{To use this really cool poster:}
\begin{enumerate}
    \item Insert the following line into the preamble,
\begin{Verbatim}[fontsize=\small]
    \makePoster[bb=0 0 570.794 329.887]{pdfyt_poster}{pdfyt_poster}
\end{Verbatim}
The optional parameter should remain as it is, it adjusts the bounding
box so that the poster is properly placed.

\item Use the \texttt{poster} key in the first optional parameter of
\cs{ytRmAnnot}, like so,
\begin{Verbatim}
    \ytRmAnnot[poster=pdfyt_poster,
        deactivated=pageclose]{YouTube}{571bp}{330bp}}
\end{Verbatim}
\end{enumerate}

\subsection{Control Buttons}

The {\YouTube} rich media annotation (as created by \cs{ytRmAnnot}), comes
with six (optional) control buttons.
\bVerb\takeMeasure{\string\ytSelect[\ameta{KV-pairs}]\darg{\ameta{vID}}\darg{\ameta{width}}\darg{\ameta{height}}}%
\begin{minipage}{\bxSize}
\begin{Verbatim}[frame=single,commandchars=!(),rulecolor=\color{red}]
\ytPlayToggle[!ameta(KV-pairs)]{!ameta(width)}{!ameta(height)}
\ytStopLoading[!ameta(KV-pairs)]{!ameta(width)}{!ameta(height)}
\ytMuteToggle[!ameta(KV-pairs)]{!ameta(width)}{!ameta(height)}
\ytRewind[!ameta(KV-pairs)]{!ameta(width)}{!ameta(height)}
\ytSelect[!ameta(KV-pairs)]{!ameta(vID)}{!ameta(width)}{!ameta(height)}
\ytOpenWeb[!ameta(KV-pairs)]{!ameta(width)}{!ameta(height)}
\end{Verbatim}
\end{minipage}\endgroup
\PD The labels are self-explanatory, the \texttt{<kv-pairs>} parameter is
the standard \textsf{eforms} optional parameter for changing the
appearance of the form. The \ameta{vID} parameter for \cs{ytSelect} is
a {\YouTube} video ID.

\goodbreak
\CmdDescription We give brief descriptions of each of the six control
buttons.
\begin{itemize}
    \item \cs{ytPlayToggle}:
    This button has several functions, \textsf{PAUSE}, \textsf{PLAY}, \textsf{BUFFERING}, and \textsf{REPLAY}.
    Initially the button label is on \textsf{PAUSE} (pressing it pauses a playing video);
    the button label reads \textsf{PLAY} when the video is loaded and paused (pressing it plays or resumes
    the video); while the video is loading, the button label is
    \textsf{BUFFERING\dots}. After the video finishes playing, the button
    label is changed to \textsf{Replay}.
    \item \cs{ytStopLoading}: Pressing this button stops the streaming of the currently playing
    video. If the video is started again, there will be some buffering before the play begins.
    \item \cs{ytMuteToggle}: This button toggles and sound off and on. Button labels are
    \textsf{MUTE} and \textsf{UNMUTE}.
    \item \cs{ytRewind}: If the video is playing, this button
       stops the video, rewinds it to the beginning, and starts play again. If the video
       is paused, this button rewinds the video to the beginning, the video remains paused.
    \item \cs{ytSelect}: When this button is pressed, a response dialog opens.
       The user enters a {\YouTube} video ID into the field. On pressing OK, this video is played.

       \item[] The second parameter \ameta{vID} is the default video
       that is displayed in the input box of the response box that opens.
   \item[] \textbf{Note:} Some {\YouTube} videos are security
       restricted and cannot be played through an embedded player, such as the one used here.
       If video ID of a video that does not allow embedded playback, a dialog appears giving
       the user the opportunity to view the video on the web.
    \item \cs{ytOpenWeb}: The user has the option of pressing this button to view the
       current video on the web at \texttt{www.youtube.com}.
\end{itemize}

The first (optional) parameter can be used to modify the appearance of the
individual buttons. To modify the appearances of the buttons as a group,
use,
\bVerb\takeMeasure{\string\ytBtnPresets\darg{\ameta{KV-pairs}}}%
\begin{minipage}{\bxSize}
\begin{Verbatim}[frame=single,commandchars=!(),rulecolor=\color{red}]
\ytBtnPresets{!ameta(KV-pairs)}
\end{Verbatim}
\end{minipage}\eVerb
The key-value pairs are ones defined for form fields created by the \textsf{eforms}
package. The default definition is,
\begin{Verbatim}[xleftmargin=\amtIndent]
\ytBtnPresets{\BC{.5 0 0}\S{S}\textFont{HeBo}}
\end{Verbatim}

The second parameter of \cs{ytRmAnnot} is the name to be associated with
that annot; the name of the annot is not known until after the annot is
defined. The command \cs{DeclareYTName},
\bVerb\takeMeasure{\string\DeclareYTName\darg{\ameta{name}}}%
\begin{minipage}{\bxSize}
\begin{Verbatim}[frame=single,commandchars=!(),rulecolor=\color{red}]
\DeclareYTName{!ameta(name)}
\end{Verbatim}
\end{minipage}\eVerb
allows you to define the name prior to the creation of the annot. This is
useful if you want to place the control buttons above the annot itself. By
specifying the name, the control buttons will know the name of the annot
they are to control.

\subsection{Controls for playing a {\YouTube} video}

To actually play a video, you must pass a video ID to the underlying SWF
file. We present two methods here, through links and through a combo box.
One of the example files, \texttt{yt4pdf-2.pdf}, illustrates another method
using a popup menu.

\subsubsection{Playing a video through a link}

The command \cs{ytvId} creates a list such that when you click on it, the
video specified by the second parameter of the command is played in the
associated Rich Media annotation created by \cs{ytRmAnnot}. The associated
RMA is the one most recently defined prior to the link. If the link occurs
before the target RMA, you can use \cs{DeclareYTName} to set the name of
the target RMA for the link.
\bVerb\takeMeasure{\string\ytvId[\ameta{KV-pairs}]\darg{\ameta{vID}}\darg{\ameta{text}}}%
\begin{minipage}{\bxSize}
\begin{Verbatim}[frame=single,commandchars=!(),rulecolor=\color{red}]
\ytvId[!ameta(KV-pairs)]{!ameta(vID)}{!ameta(text)}
\end{Verbatim}
\end{minipage}\endgroup
\PD The first parameter takes the usual key-value pairs for links created
by the \textsf{eforms} package. The second parameter is the video ID to be
played. The third parameter is the text to be displayed by the link,
usually the title of the {\YouTube} video.

\cs{ytvId} loads and plays the specified video; there is an
\texttt{*}-form of this command,
\bVerb\takeMeasure{\string\ytvId*[\ameta{KV-pairs}]\darg{\ameta{vID}}\darg{\ameta{text}}}%
\begin{minipage}{\bxSize}
\begin{Verbatim}[frame=single,commandchars=!(),rulecolor=\color{red}]
\ytvId*[!ameta(KV-pairs)]{!ameta(vID)}{!ameta(text)}
\end{Verbatim}
\end{minipage}\eVerb
When this form is used, the {\YouTube} thumbnail image for the video is
displayed. The player does not
request the video until the play button is pressed.

You can set the appearances for a all links created by \cs{ytvId} by using
\cs{ytvIdPresets}
\bVerb\takeMeasure{\string\ytvIdPresets\darg{\ameta{KV-pairs}}}%
\begin{minipage}{\bxSize}
\begin{Verbatim}[frame=single,commandchars=!(),rulecolor=\color{red}]
\ytvIdPresets{!ameta(KV-pairs)}
\end{Verbatim}
\end{minipage}\eVerb
The key-value pairs are ones defined for form fields created by the \textsf{eforms}
package. The default definition is
\begin{Verbatim}[xleftmargin=\amtIndent]
\ytvIdPresets{\linktxtcolor{webbrown}}
\end{Verbatim}

\subsubsection{Playing a video using a combo box}

You can created a combo box with a play list. There are three commands
that create the combo list, \cs{ytPlayList}, \cs{ytComboList}, and
\cs{ytComboBtn}.
\bVerb\takeMeasure{\string\ytPlayList\darg{\ameta{default\_vId}}\darg{\ameta{playlist}}}%
\begin{minipage}{\bxSize}
\begin{Verbatim}[frame=single,commandchars=!(),rulecolor=\color{red}]
\ytPlayList{!ameta(default_vId)}{!ameta(playlist)}
\end{Verbatim}
\end{minipage}\eVerb
This command sets the play list to be displayed in the combo box, it needs
to be executed before the actual creation of the combo box (using
\cs{ytComboList}). The first parameter is the default video ID, this title
will be initially displayed by the combo box. The \ameta{playlist} is
an array of video IDs and title pairs. The \ameta{playlist} is conveniently defined
within the \cs{declarePlayList} command:
\bVerb\takeMeasure{\string\declarePlayList\darg{\ameta{\cs{plCmd}}}\{\%}%
\begin{minipage}{\bxSize}
\begin{Verbatim}[frame=single,commandchars=!(),rulecolor=\color{red}]
\declarePlayList{!ameta(\plCmd)}{%
    !ameta(array-of-vIDs-titles)
}
\end{Verbatim}
\end{minipage}\eVerb The array of video IDs and title pairs are saved under the command name \ameta{plCmd}.
For example
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\declarePlayList{\playList}{%
    [(GZ9e3Dy7obA)(Kung-Fu Fighting {(Bruce Lee version)})]
    [(eNzrn8-JFSE)(Open at Adobe)]
    [(5y9-EVmreU4)(Lori's Corner: Episode \#1)]
}
\end{Verbatim}
The format for each pair is \texttt{[(\ameta{vId})(\ameta{title})]}. Notice that in the case
of the Bruce Lee video, the title itself contains parentheses; to avoid parsing errors when
the \pkg{eforms} package builds the combo box, \emph{enclose these parentheses in a pair of matching braces}.

In the example above, the array, in its correct format, is loaded
conveniently into a macro \cs{playList} declared through \cs{declarePlayList}. The macro may then be passed as the
second parameter of \cs{ytPlayList}. Thus, an example of the use of
\cs{ytPlayList} is
\begin{Verbatim}[xleftmargin=\amtIndent]
\ytPlayList{eNzrn8-JFSE}{\playList}
\end{Verbatim}

There is a convenience command, \cs{ytIdTitle}, that is used to build
a \cs{ytPlayList}.
\bVerb\takeMeasure{\string\ytIdTitle\darg{\ameta{vId}}\darg{\ameta{title}}}%
\begin{minipage}{\bxSize}
\begin{Verbatim}[frame=single,commandchars=!(),rulecolor=\color{red}]
\ytIdTitle{!ameta(vId)}{!ameta(title)}
\end{Verbatim}
\end{minipage}\eVerb
The above example can the be re-written as,
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\declarePlayList{\playList}{%
    \ytIdTitle{GZ9e3Dy7obA}{Kung-Fu Fighting {(Bruce Lee version)}}
    \ytIdTitle{eNzrn8-JFSE}{Open at Adobe}
    \ytIdTitle{5y9-EVmreU4}{Lori's Corner: Episode \#1}
}
\end{Verbatim}

\paragraph*{The combo box.} The syntax for the combo box itself is
\bVerb\takeMeasure{\string\ytComboList[\ameta{KV-pairs}]\darg{\ameta{width}}\darg{\ameta{height}}}%
\begin{minipage}{\bxSize}
\begin{Verbatim}[frame=single,commandchars=!(),rulecolor=\color{red}]
\ytComboList[!ameta(KV-pairs)]{!ameta(width)}{!ameta(height)}
\end{Verbatim}
\end{minipage}\eVerb
The \cs{ytComboList} is a combo box of video Ids and titles. The user
selects a video based on its title, then presses the \textsf{PLAY} button
(see \cs{ytComboBtn} below). This command is executed \emph{before}
\cs{ytComboBtn} to set the play list, and the default value.
\PD\begin{itemize}
   \item \ameta{KV-pairs}: (optional) The key-value pairs associated with an
   \textsf{eforms} form field, used to change the appearance of the field.
   \item \ameta{width}: The width of the combo box
   \item \ameta{height}: The height of the combo box
\end{itemize}
The appearance can be changed locally by the optional first parameter. The
command \cs{ytComboListPresets} is used to change all combo lists create
by \cs{ytComboList}. The command takes has one parameter, the key-value
pairs for changing the appearance. The default definition is
\verb!\ytComboListPresets{}!.

Originally, I visualized only one combo box per page, recently that
mind-set has changed. Should you want several combo boxes, as created by
\cs{ytComboList}, each box must have a unique name. To that end
\bVerb\takeMeasure{\string\ytNewBaseName[\ameta{name}]}%
\begin{minipage}{\bxSize}
\begin{Verbatim}[frame=single,commandchars=!(),rulecolor=\color{red}]
\ytNewBaseName[!ameta(name)]
\ytResetBaseName
\end{Verbatim}
\end{minipage}\eVerb
The first command, \cs{ytNewBaseName}, has one optional parameter, if no
parameter is supplied, then a base name will be generated; otherwise,
the title of the combo box will be based on the \ameta{name} passed to
it.  For the command \cs{ytResetBaseName}, the first command effects the JS
and the field name of \cs{ytComboBtn} described below.
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()]
\begin{itemize}
\item \ytNewBaseName\relax\ytPlayList{!ameta(default_Id)}{\playListii}%
      \ytComboList{2.5in}{11bp}\kern1bp\ytComboBtn{33bp}{11bp}
\item \ytNewBaseName[Listiii]\ytPlayList{!ameta(default_Id)}{\playListiii}%
      \ytComboList{2.5in}{11bp}\kern1bp\ytComboBtn{33bp}{11bp}
\end{itemize}
\end{Verbatim}
\textbf{\textcolor{red}{Note:}} Because \cs{ytNewBaseName} has an optional
argument, you should place a \cs{relax} after \cs{ytNewBaseName} to prevent
premature expansion of the \cs{ytplayList} command that follows.

\newtopic Once the selection has been made from the combo box, the user
can play the selection by pressing the button created by \cs{ytComboBtn}.
\bVerb\takeMeasure{\string\ytComboBtn[\ameta{KV-pairs}]\darg{\ameta{width}}\darg{\ameta{height}}}%
\begin{minipage}{\bxSize}
\begin{Verbatim}[frame=single,commandchars=!(),rulecolor=\color{red}]
\ytComboBtn[!ameta(KV-pairs)]{!ameta(width)}{!ameta(height)}
\end{Verbatim}
\end{minipage}\eVerb
\textbf{\textcolor{red}{Note:}} If you hold down the shift key and click on
the button, the thumbnail poster is loaded, and the player is ready to
play the video.
\PD\begin{itemize}
   \item \ameta{KV-pairs}: (optional) The key-value pairs associated with an
   \textsf{eforms} form field, used to change the appearance of the field.
   \item \ameta{width}: The width of the combo box
   \item \ameta{height}: The height of the combo box
\end{itemize}
The appearance can be changed locally by the optional first parameter. The
command \cs{ytComboBtnPresets} is used to change all combo lists create
by \cs{ytComboBtn}. The command takes has one parameter, the key-value
pairs for changing the appearance. The default definition is
\verb!\ytComboBtnPresets{}!.

\subsection{Using the \textsf{popupmenu} package}

The \pkg{popupmenu} a required package, \pkg{yt4pdf} adds some commands and
JS to facilitate its usage. The demo file for this feature is
\texttt{yt4pdf-2.tex}, where you will find some comments in the source file.

In the preamble, we define our menu structure,

\begin{Verbatim}[numbers=left,xleftmargin=\leftmargini,fontsize=\fontsize{9}{11}\selectfont]
\begin{popupmenu}{YTMenu}
    \puIdTitle{Select a You Tube Video}{} % A title has no yt Id
    \begin{submenu}{title=Music Videos}
        \puIdTitle{Ink Spots - If I didn't care}{rvwfLe6sLis}
        \puIdTitle{Ink Spots - My Prayer}{h7KJCns5v3g}
    \end{submenu}
    \begin{submenu}{title=Adobe Related Videos}
        \puIdTitle{Open at Adobe}{eNzrn8-JFSE}
        \puIdTitle{Lori's Corner Episode \#1}{5y9-EVmreU4}
        \puIdTitle{Intro to PDF Portfolios}{T9Yzo_hlwP0}
    \end{submenu}
\end{popupmenu}
\ytPopupMenuData{\YTMenu}
\end{Verbatim}
The \cs{puIdTitle} is a convenience macro to enter the menu data; the
first argument is the title of the {\YouTube} video, the second argument
is the {\YouTube} ID. There may be several \texttt{popupmenu} environments, each
with a different name. After the last such environment, execute the
\cs{ytPopuMenuData} command, seen in line~(12). Its argument is a token
list of all popupmenus; here, we have only one. If there are several, they
are listed as follows:
\begin{Verbatim}[xleftmargin=\leftmargini]
\ytPopupMenuData{\YTMenu\myEduVids\myMusicVids}
\end{Verbatim}

The menu is displayed as an mouse-over action of button, here is the
verbatim listing from \texttt{yt4pdf-2.tex}

\begin{Verbatim}[numbers=left,xleftmargin=\leftmargini,fontsize=\fontsize{9}{11}\selectfont]
\DeclareYTName{ytInWindow}
...
\newcommand{\myPBPresets}{%
    \CA{YT Menu}\textColor{0 0 1}\W1\BC{}\textSize{0}\S{S}
    \AA{\AAMouseEnter{\JS{ytPopupMenu("\ytCurrRMAName",YTMenu)}}}}
\setWindowDimPos{%
    position={halign=center,valign=center,hoffset=0,voffset=0},
    width={default=571},height={default=330}}%
\setlength{\pichskip}{3pt}
\parpic(.25in,.25in){%
\parbox{.25in}{\offinterlineskip\resizebox{.25in}{!}{%
    \ytRmAnnot[windowed,poster=yt_poster,deactivated=pageclose]%
    {ytInWindow}{72bp}{72bp}%
}}}
\pushButton[\presets{\myPBPresets}]{myYTMenu}{20bp}{5bp}
On this page, the You Tube annotation is icon size and the
video is played in a floating window.
\end{Verbatim}
\textbf{Comments:}
\begin{itemize}
    \item In line~(1) we declare the name of the {\YouTube} annot to be
    used. We do this because we need to use the name before the annot is
    defined. The annot itself is not defined until line~(12).
    \item Lines~(3)--(5): Define a command to be used for passing the
    button attributes for the \texttt{myYTMenu} button (seen in
    line~(15)). In line~(5) we define the action for the button; it is a
    mouse enter action that executes the \texttt{ytPopupMenu} JS function
    defined in the \texttt{yt2pdf} package. This function takes two
    arguments, the first is the name of the target Rich Media Annotation
    hat will display the videos, this name is \verb!"\ytCurrRMAName"!,
    where \cs{ytCurrRMAName} holds the name of the most recent {\YouTube}
    annotation. The second argument is the name of the menu data (defined
    by the \texttt{popupmenu} environment.
    \item Lines~(9)--(14): We create an annot so that it appears as an
    icon, the text of the paragraph wraps around the icon. This is what we
    do with the \cs{parpic} command. In lines~(12)--(13), we create the
    {\YouTube} annot using \cs{ytRmAnnot}.
    \item In line~(15) we have a button with a mouse rollover action. Note
    we pass the earlier defined presets to this button.
\end{itemize}
See the complete source file in \texttt{yt4pdf-2.tex}.


\section{Language localizations}

The default language for \textsf{yt4pdf} is English; the English strings
that \textsf{yt4pdf} uses are listed below. These can be redefined as
desired.
\begin{Verbatim}
\newcommand{\ytStrPLAY}{PLAY}
\newcommand{\ytStrREPLAY}{REPLAY}
\newcommand{\ytStrPAUSE}{PAUSE}
\newcommand{\ytStrBuffering}{Buffering...}
\newcommand{\ytStrStopLoading}{Stop Loading}
\newcommand{\ytStrMUTE}{MUTE}
\newcommand{\ytStrUNMUTE}{UNMUTE}
\newcommand{\ytStrREWIND}{REWIND}
\newcommand{\ytStrLoadVideo}{Load Video}
\newcommand{\ytStrWatchOnWeb}{Watch on YouTube}
% response dialog box associated with ytSelect()
\newcommand{\ytRespQues}{Enter the YouTube Video ID}
\newcommand{\ytRespTitle}{Load a Video}
\newcommand{\ytRespLabel}{ID:}
% alert error messages
\newcommand{\ytStrErrorVideoNotFound}{Error: Video not found}
\newcommand{\ytStrErrorNoEmbed}{Error: This video does not allow
    embedded playback \r\r Would you like to view this video
    on the web?}
\newcommand{\ytStrConnecTimedOut}{Connection timed out, try again.}
\end{Verbatim}

\bigskip

That's all for now, I simply must get back to my retirement. {\dps}

\end{document}