Thursday, April 23, 2015

Footnotes and Endnotes in iBooks Author

wordcloud for endnotes
In a riff on the most famous foot-noter of all (Edward Gibbon, “The History of the Decline and Fall of the Roman Empire” | Wikipedia | Gutenberg), Stanford alum Bruce Anderson delightfully chronicles “The Decline and Fall of Footnotes” only to conclude:
More than anything, Gibbon should make us rethink our attitude toward footnotes and the attendant deathwatch. The emphasis in our schools has been to replicate the form rather than the content or style of a good footnote. We should remember that reading Gibbon without the footnotes is like listening to Mozart without the 16th notes; the music of each lacks its distinctive, ineffable magic when the little notes are taken away.

Ideally, footnotes are also a graceful acknowledgement that today's community of scholars is linked to and dependent on yesterday's community. As Sir Isaac Newton modestly noted in a letter to Robert Hooke, "If I have seen further [than you and Descartes] it is by standing upon the shoulders of Giants.” If Newton can be so generous, it should be easy for the modern scholar to acknowledge his or her intellectual debts.

The very word "scholar" has its root in the Latin "schola" or "school" and bespeaks a community or network of people striving together for understanding. "Footnotes are reminders that scholarship is an intrinsically communal enterprise--building on, revising or replacing the work of predecessors," noted Kenneth L. Woodward in Newsweek. Scholars are not "Lone Rangers, going it alone."

Still, footnotes and endnotes in paper documents are a source of pain and suffering to readers and authors alike. Perhaps the digital era will bring relief.
The problem with notation in paper documents?
Except for their location in a document, footnotes and endnotes are both used to achieve one or more of the following four objectives:
  • To acknowledge the words and work of other authors - without attribution, it’s plagiarism.
  • To provide authority for assertions of fact and law.
  • To provide support for arguments or points of discussion.
  • To provide additional information or references which may be of interest to the reader but which are not central to the main text.

These are important and necessary, especially in academic writing.

Because footnotes and endnotes in paper documents are physically separated from the text that they refer to, readers require help in correctly connecting them. This is usually done using matching pairs of superscripted numbers, asterisks or other symbols. One appears at the end of the word, phrase or block quote to which the note refers. The other appears to the immediate left of the note at the end of the page (footnote) or to the left of each item in a list of notes at the end of the book or chapter (endnotes). Given the 500 year history or print, this is apparently the best that can be done with paper and probably why Noel Coward quipped that, “Coming across a footnote is like going downstairs to answer the doorbell while making love.” (It is peculiar that footnotes should so often bring amorous intimacies to mind. The historian Philip Guedalla once remarked that Edward Gibbon lived out most of his sex life in his footnotes. [from Bruce Anderson, cited above])
The promise of notation in digital documents.
Because the modern eReader must contend with different orientations (portrait vs landscape) and a wide range of variously sized viewports, it would be quite difficult to develop a skeuomorphic rendition of traditional footnotes in documents that will only be read on digital devices. This calls for a change in our nomenclature. Hereinafter, we use the term “author note” to refer to the things that help digital authors pursue any of the four objectives enumerated above. The “author” qualifier is needed in order to distinguish their notes from the reader notes supported in many eReaders such as the iBooks app..
The advent of ePub 3.
Under the
EPUB 3 standard, author notation is handled via a pop-up that is invoked by the reader tapping on hyperlinked text. Thus, the context and association of such notation is much clearer to the reader without being as much of a distraction as a paper-based footnote would be. A popup note in an ePub 3 document may look like this in the iBooks app:

Pop-up Notes in EPUB 3

Although superscripted numbers are used in the image above (screenshot taken from Apple’s “”Flowing Example 3.1), there is no need to do so. Because any text string can be used as the hyperlink that will invoke a notational pop-up. Using something longer such as “NOTE” or “REFERENCE” would certainly make it easier for readers to accurately tap these links.

On Tuesday, May 22, 2012, Apple sent out an email to its iTunes Connect mailing list that included the following paragraph:
EPUB 3 Support
iBooks and the iBookstore now support EPUB 3 for flowing books. EPUB 3 includes new features to enrich your book including the pop-up footnote functionality.

In this context, the term “footnote” is a bit of a misnomer. The ePub 3 popup note in the iBooks eReader has nothing to do with the foot of a page. These are author notes. Apple probably reasoned that this skeuomorphic example would be more easily grasped, at least initially.

Pop-up author notes are a good thing for readers in that they are now so much more easily and conveniently accessed. No longer must we correlate small superscripted numbers in the text with notes that appear at the bottom of the page (footnotes) or, worse, at the end of the book or chapter (endnotes). This is such an elegant alternative that I think we can conclude that footnotes and endnotes have been rendered obsolete by these new author notes and, thus, have no legitimate place in digital documents.
So how does one include author notes in an iBooks Author project?
The Books Author application currently has no explicit provision for any kind of notation, modern or otherwise. There is no clearly developed and labeled way for an author to pursue any of the four purposes of author notation enumerated above.

Consequently, users of the iBooks Author application have resorted to various workarounds that attempt to achieve some semblance of the author notation functionality readily available in ePub 3. Some of these methods are better than others but none are as good as a purpose-built author notation function by Apple could be. Some of the more popular of these workarounds include:
  • Using the Pop-Over widget to simulate ePub 3 style popup note.
  • Using the hyperlink function to create a round trip endnotes experience
  • Re-purposing the Glossary
  • Re-purposing Bookmarks

Taking these in reverse order, the two re-purposing tactics are bad ideas because doing so precludes their conventional use and conflicts with common reader expectations. As well, we have better options.

While endnotes are familiar, they are generally disliked by readers because using them is such a distraction. A digital implementation of endnotes can ease some of that pain with carefully constructed hyperlinks but the reader must still click through a unique round-trip path in order to maintain their “place.” Many readers simply ignore the endnotes. Here, too, we have better options.

The best available workarounds make use of the iBooks Author Pop-Over Widget. Here are two ways to use the Pop-Over widget to implement author notes in iBooks Author. As we’ll see, each has a unique set of pros and cons. The hope of this blog post is that one or the other or both will tide you over until Apple provides something better.
The visible graphic method:

visible graphic.002

Create a small graphic image that is wider than it is tall. It could be an icon (thought bubbles are popular) or an image of text as shown. I use “NOTE” but it could just as well be CITATION, EXAMPLE, REFERENCE, etc. as long as your convention is consistently applied throughout your book. Using all caps and sharply contrasting colors will also help the reader notice and understand what their options are. The example pictured is 54 x 28 pixels.

visible graphic.003
In landscape mode, go to the page where you want to place the “hot spot” that will invoke the author note and select the pop-over widget from the widgets menu.
visible graphic.004

Drag and drop the small text image onto the pop-over widget.
visible graphic.005

Insert the text and images that constitute your citation, reference, note etc. Note that the pop-over widget supports text, images and hyperlinks. Webpage hyperlinks enable external references. Internal hyperlinks can transport readers to a chapter, section, page number or any figure in the book but reader “place keeping” can become a thorny issue.
visible graphic.006

With the pop-over image selected, open the Wrap pane in the Inspector, uncheck "Object causes wrap" and use "Inline (moves with text)" for Object Placement.
visible graphic.007

Drag the pop-over image to where you want it to appear, adjust and resize it (smaller) so that surrounding text formatting is not disrupted. Presenting the reader with a more easily tapped target can only be done by making this image wider. Height will be very constrained. It may be necessary to add spaces to separate this graphic from surrounding text.
visible graphic.008

Close-up. The image is now 29 px wide by 15 px high.
visible graphic.009

Landscape orientation. This will work in all orientations and will be impervious to subsequent text editing because the image will follow the text.  Due to its small size, it may be difficult for some readers to tap accurately the first time.

visible graphic.010
Portrait orientation.

Pro: this works in either portrait or landscape orientation
Pro: this is not affected by subsequent editing
Con: the “hot spot” thus created may be difficult for some readers to tap accurately.
The invisible graphic method:

invisible graphic.002

Create a small, square graphic image. Use any solid color. I am using a black square *.png file that is 64 x 64 pixels.
invisible graphic.003

In landscape mode, go to the page where you want to place the “hot spot” that will invoke the author note and select the pop-over widget from the widgets menu.
invisible graphic.004

Drag and drop the small, solid color image onto the pop-over widget.
invisible graphic.005

Insert the text and images that constitute your citation, reference, note etc. Note that the pop-over widget supports text, images and hyperlinks. Webpage hyperlinks enable external references. Internal hyperlinks can transport readers to a chapter, section, page number or any figure in the book but reader “place keeping” can become a thorny issue.
invisible graphic.006

Add text that will serve as the “trigger” to this effect. In this example, I use [NOTE]. This could be anything: CITATION, EXAMPLE, REFERENCE, etc. as long as your convention is consistently applied throughout your book. Using all caps and a different text color will also help the reader notice and understand what their options are.

invisible graphic.007

With the pop-over image selected, open the Wrap pane in the Inspector, uncheck "Object causes wrap" and select “Floating (doesn’t move with text)” for Object Placement.

invisible graphic.008

Drag the pop-over image on top of the [NOTE] text just created so that it is completely obscured. This will be the “hot spot” that invokes the pop-over author note.
invisible graphic.009

With the pop-over image selected, use the Graphic pane of the Inspector to set the opacity of the pop-over graphic to zero. This will create the illusion that tapping on the target text invokes the author note.
invisible graphic.010

Now, clicking on the text string “[NOTE]” appears to invoke the author note pop-over. This is easily done because the invisible hot spot is large enough so that even the most “fat fingered” readers can still succeed in making the author note appear. That is, in landscape mode.

invisible graphic.011

This does not work in portrait mode. I’ve reset the opacity of the hot spot to 100% so that the movement of this otherwise invisible element away from the text “trigger” is apparent. This breaks the illusion. It is not currently possible to have a pop-over graphic this large and set to Inline (moves with text) …
invisible graphic.012

… that does not disrupt formatting.
invisible graphic.013

Thus, one should disable portrait mode in the inspector document pane.

Pro: the footprint of the “hot spot” thus created can be much larger than the “target” text making it easier for readers to invoke an author note.
Con: this only works in landscape mode (portrait mode needs to be disabled)
Con: subsequent editing can mis-align hot spot and target.
These are the best workarounds I’ve been able to come up with but they both suffer from the fact that the “trigger” is a graphic object that was not designed to work with text. Text, of course, is what author notes always refer to.
Identifying the best solution:

Authors should not have to choose between readability and thorough exposition. As well, the reader should not have to struggle to keep their place. The Noel Coward quip needn’t be uttered or even thought of in the digital era.

First, we consider what the reader’s experience should be like and then we can turn our attention to ways and means to achieve it. One thing is already clear. Authorial notes should be hyperlinked text, not graphic elements.
… what should the reader experience be:

The reader should …
… never loose their “place” when opting to find out what an author note has to say to them.
… be able to easily invoke an author note with a single operation regardless of screen size or orientation
… easily recognize an author note and be able to differentiate it from other kinds of hyperlinks
… be able to easily see what kind of authorial note it is in advance (this also speaks to accessibility requirements).
• citation or reference - reference to source (enables location and verification)
• discussion - supporting facts and reasoning (in greater depth than main text)
• supplement - information or references facilitating further, in-depth study
• example - case study, anecdotal information, etc.
• evidence - tables/charts corroborating assertions in main text
• aside - interesting or amusing corollary information
• etc.
… be able to select and copy all content in author notes to be used elsewhere (e.g. reader notes, further study, research, etc.).
… how can Apple help authors meet these needs?

The pop-up used in ePub 3 and the pop-over used in iBooks Author provide the ideal solution for assuring reader place holding while consulting author notes. As text-based hyperlinks, the author may employ a number of textual conventions to make it more easily recognized and invoked. With a pop-up, place holding and utility are assured because it appears in context and is easily dismissed. As text, the hyperlink will flow and respond to changes in font face, size and style. Color may be controlled in the template as is the case other types of hyperlinks.

There are already six different types of hyperlinks in iBooks Author as follows:

Web Page (URL)
Email Message (To: address, Subject)
Bookmark (Name)
Figure (In: Entire Book/Chapter, Style [9])
Chapter or Section (auto listed)
Page (type page number)

Proposed is a seventh type of hyperlink, the author note:

Author Note (no parameters, pop-up fully editable)

This pop-up should accept text, images and selected widgets (Gallery, Media, Keynote, 3D and HTML) and include full screen options where appropriate.

The reader will be able to select and copy text in an author note for use in verifying citations, re-purposing data, etc. Readers could incorporate some or all of this information in their Reader Notes and, because those can generate flash cards, incorporate that into their study routine. Hyperlinks to web-based references can be copied as well as followed. Returning from Safari to iBooks maintains the reader’s “place.”

For scholars of every stripe, from student to tenured full professor, this is a much more productive environment.
The problem of differentiating hyperlinks.

With seven different types of hyperlinks, how is the reader to know in advance what kind of hyperlink it is and, in the case of author notes, what the purpose of that author note might be. Presently, the reader has only the color of the hyperlink to go on and several hyperlinks use the same color in many templates. Clearly, the reader needs more than this.

Of course the author could implement conventions in a multi-touch book that provide readers with this needed information. For example, all hyperlinks could use square brackets to enclose explicitly titled hyperlinks such as the following examples:
[author note: citation for this block quote]
[author note: hyperlink to original source]
[author note: 3D model of xyz molecule]
[author note: HTML widget: opinion poll]

[web page: in-depth info on xyz molecule]
[chapter 2, section 1: examples of recursive routines]

Another, possibly better, approach would be to implement alternate text and title (tool-tip) text for hyperlinks in multi-touch books just as with images and hyperlinks in web pages. In this case, iBooks Author would present a user interface for author notes and other hyperlinks that would include fields for alternate and title text. Sighted readers would tap and hold the hyperlink to see tooltip-like title text whereas visually impaired readers would hear the alt text read to them and have the option of following the hyperlink or not.
The problem of one-way hyperlinks.
Although this isn’t an issue with the proposed author notes hyperlink because that hyperlink uses an in situ pop-up or with web page hyperlinks because the Safari handoff always returns to the point or origin, other kinds of hyperlinks (figure, bookmark, chapter or section, pages) cause place holding and user interface consistency issues by failing to provide for round-trip passage. Once transported to another part of the book, the reader has no way to return the reader to where they were.

Authors can engineer a round-trip experience with these problematic hyperlinks if and only if there is but one link to that other place in the book. In that case, the author can create a hyperlink back to the originating page. However, if there is more than one hyperlink to that specific other place in the book, the author cannot know which link brought the reader there and, so, cannot devise a return path.

A possible solution to this is to have yet another new kind of hyperlink, the Return hyperlink. Whenever a one-way hyperlink is used, the author is additionally prompted to create a Return link at the destination by entering the text of that Return hyperlink.

In the iBooks app, tapping a Return hyperlink will consult the history file identifying the last hyperlink used and return the reader there.
The problem of un-hidden resource pages.

For some books, the author wishes to provide resources that can only be accessed from a certain place in the book. The information presented might be confusing or difficult to understand if it is encountered out of context.

Hidden pages that can only be accessed via a hyperlink would help the author avoid this unwanted outcome. A Return link would be absolutely essential less the reader become stranded on a hidden page.

Such a feature could be an effective alternative to pop-up author notes where the author has a great deal of additional content to share with the reader.

Placing a suggested reading page on a hyperlinked hidden page might be useful as a way to postpone the readers interaction with it until after the content exposition has been largely or mostly completed.
Summary of Feature Requests:
Author Note. This primary feature request calls for a new kind of hyperlink called Author Note. This text-based hyperlink will invoke a pop-up that is similar in appearance to the pop-over. The pop-up author note can contain text, images and selected widgets (Gallery, Media, Keynote, 3D and HTML) and include full screen options where appropriate. Readers will be able to select and copy all or any part of the contents of an author note for use elsewhere in the book (reader notes) or outside the book.

Return Hyperlink. The return hyperlink option is invoked whenever the author opts to use a hyperlink that will transport the reader to another part of the book. The author will have the option of using this feature or not and specifying the text of the hyperlink.
Hidden Pages. Authors will have the ability to create hidden chapters, sections and pages that will only be accessible via hyperlink. The return hyperlink will be an essential companion feature to this.
Taking action:

If you agree that some or all of these enhancements requests would be good for you and other iBooks Author users, here’s what to do.

In iBooks Author, go to the iBooks Author menu (upper left corner of screen, just to the right of the Apple menu) and select Provide iBooks Author Feedback. Fill out the form and feel free to select, copy and paste from here if you like.

Tuesday, February 24, 2015

Optimizing iPad Video for iBooks Author and Pages

Including video in an eBook, especially an eTextbook, has become essential and expected. If a still image is worth a thousand words, then the potential explanatory power of an image moving at 30 frames per second must be exponentially greater. Getting from potential to actual value, however, requires compelling content and clear, efficient video.


The preeminent tools for creating eBooks and eTextbooks containing video are iBooks Author and Pages, both from Apple. The iBooks Author app comes bundled with MacOS X which is free and Pages comes bundled at no extra cost with all new Macs. There are no other apps on any platform that match both the affordability and ease of use of Pages and iBooks Author.


However, there have been issues with the way these apps have handled eBook video in the past. Some of those issues have been documented here. This post is a re-examination of those issues to assess the current state of video in eBooks produced by these two apps. Have things gotten better, remained unchanged or gotten worse? That is the question.

The iBooks Author (iBA) application has had difficulty handling video efficiently. In version 1.0, authors had to meet very strict and vague encoding requirements in order to avoid rejection of a video file. In succeeding versions, Apple addressed the many issues arising from this situation by incorporating a video optimizing routine that would re-encode any video brought into an iBA project via the Media widget. Early versions of this new functionality solved the problems that authors were having with video encoding for their eBook projects but they did so by making those video files unnecessarily large. It was quite common for a video file to become three times larger than the original after being “optimized” in iBooks Author.

Jan Ozer developed a clever way to circumvent the iBA video optimizer using custom presets for the Handbrake video transcoder and he offered how-to workshops on that tactic. In June of 2014, however, Apple updated iBA and rendered this workaround ineffective.

Ozer iBA Workshop

The current version of iBA (2.2) was released in October of 2014. The status of the video optimizer has never been referenced in any iBooks Author version history or Read Me file. Our knowledge of it has only come about by comparing input to output and then inferring what goes on within the innards this black box.

Even less well known is the history of video handling in the Pages application. The current version of Pages (5.5.2) has an export to ePub function which silently and invisibly invokes a video optimizer that, like iBA, calls upon system-level routines such as AVConvert to optimize your media files.” Pages seems to have followed iBooks Author with respect to handling the inclusion of video in eBooks without requiring authors to become expert in the art of video compression.

So with the increasing importance of video in eBooks and especially in eTextbooks, it is important to stay abreast of the ways in which Apple’s iBooks Author produces *.ibooks files containing video and how Apple’s Pages produces *.epub files containing video even if Apple isn’t very forthcoming on the topic.


Both Pages and iBooks Author output eBooks (*.epub or *.ibooks files) that share the same architecture. Each eBook is actually a collection of various files and folders in an enclosing folder that has been archived using the Zip standard. The suffix of the resulting *.zip file is then changed to *.epub or *.ibooks which enables eReaders to know that they can be rendered as eBooks. The free
ePub Zip/Unzip application handles this chore very nicely.

It’s being able to “look inside” that enables us to see what these video optimizers have done to the video we provided, comparing input to output, before to after. An inexpensive ($0.99) app named
MediaInfo provides us with detailed information on each version of the video we wish to examine. Less information can be gotten for free by using QuickTime X Player’s Get Info function.

So our methodology is to bring video files into our iBA and Pages projects, export as *.ibooks or *.epub, then deconstruct the resulting eBook by unzipping it, finding the video files, developing information about those files and, finally, comparing and analyzing the differences.


Raw data, including test videos, with detailed analyses may be found in the following
eTextbook created with iBooks Author. Download this *.ibooks file and read it with the iBooks app on an iPad 2 or newer or a MacOS X 10.9 or newer computer. This volume will illustrate by examples precisely how the current (2.2) version of iBooks Author handles ingested video. It will also document what Pages does to ingested video.



The iBooks Author (iBA) application has improved video handling to the point where corrective action after export is no longer warranted or recommended. The media optimizer in iBA 2.2 will increase file size only slightly over what was ingested. However, optimizing video with Handbrake prior to ingestion produced significantly smaller video files of equivalent quality and this is recommended as current best practice. The eTextbook cited above contains a link to the custom Handbrake preset used in these investigations with instructions on how to import it into the Handbrake app and use it.

Boy with Big Book

The Pages app, unfortunately, has not improved as much. Video files ingested by Pages 5.5.2 are typically inflated to three times their original size or more. The best practice response to this unfortunate situation is to use the deconstruction techniques used in this investigation to replace the inflated video file with a version encoded by Handbrake using the aforementioned preset. Stepwise instructions on how to do this are found in the eTextbook cited above.

Wednesday, December 24, 2014

Video Bloat in Pages ePub Exports and How to Fix It

Pages 5.5.1 for MacOS X has an excellent ePub export option. That export option includes elements of ePub 3 such as embedded audio and video so Pages, being free with MacOS X, is a very attractive application for teachers at all levels who want to create eTextbooks containing rich media. However, there is a problem with Pages ePub video that this blog post will identify, document and provide solutions for. First, the problem statement.
Starting with Apple’s ePub template, we create a test project. To follow along, download the “ePub best practices” document from Apple’s “
Creating ePub files with Pages” support document, open it in Pages and do File > Save as template … which makes this template available to us now and in the future.
After we have the template saved, we add a 75 MB 1280 X 720 video with a duration of 5 minutes and 36 seconds (
download) to the still open Pages document. It now looks like this:

Video Quality Blog Post.001

The next step is to export this document as an ePub (File > Export To > ePub …). As we look at the output of this process in the Finder, we see that the ePub is about 280 MB despite the fact that the parent file, the Pages project, is only 80 MB in size. Here’s what that looks like:

Video Quality Blog Post.002

As far as I know, there is no application that can add useful data to source video. So, what is going on? Could this be an instance of unnecessary …

Video Quality Blog Post.003

… video bloat? The following delves into how to investigate that possibility. The first step in that investigation is to download ePub Zip Unzip so that we may peer inside the ePub file structure, find the video file and compare it with the original that was initially fed to Pages. This app has a very simple user interface that looks like this:

Video Quality Blog Post.004

The reality of an ePub file is that it is actually what is called a package file, a folder containing a variety of files that has been archived into a single file using the Zip compression algorithm. What ePub Zip Unzip does in this first step is simply to unzip the file into the folder it started out as. Once we have unzipped the ePub file, we can open this folder and examine its contents. Specifically, we’re interested in the video media because this is the only thing that we added to the Pages project beyond the template itself. Here is what we see:

Video Quality Blog Post.005

Clearly, we are looking at an instance of file bloat. The video file has grown more than 200 MB beyond its original size. This is not likely to be an improvement. To determine why this is so, we turn to another free, open source app called MediaInfo. Note that QuickTime X Player will also provide the most essential of this data but MediaInfo can provide additional data that is very useful to advanced users. Here’s what MediaInfo says about the original file:

Video Quality Blog Post.006

… and the video file exported by Pages:

Video Quality Blog Post.007

Here’s a table summarizing this analysis:

Video Quality Blog Post.008

The change in suffix from .mp4 to .m4v is inconsequential but the change in bit rate is key. The bit rate is 3.5 times greater than the source file! This is precisely what has inflated the file size. The formula for file size is bit rate times duration. So, will our readers benefit from this larger, longer to download file? Let’s see.

Link to full size version of this video: click here (opens in a new window)

Quite frankly, I see no improvement. Certainly not an improvement justifying an additional 200 MB in file size.

So that’s the problem. Now, how do we fix it? We already have some terrific clues. We have the ePub on the operating table and opened up so we can see and operate upon all of the internals. Why not try to replace the bloated video with the more efficient one that we started with. Here’s how:

First, we move the better file into the same location as the bloated version. Note that they have different names. This complicates things just a little bit. So copy the good video into the same folder as the bad video, like this:

Video Quality Blog Post.010

This is a simple drag and drop operation in the Finder. Next, we copy the full name of the bad video like so:

Video Quality Blog Post.011

Move the bad (bloated) file to the trash like so:

Video Quality Blog Post.012

Select and paste the name of the bad (bloated) file renaming the good file like so:

Video Quality Blog Post.013

Accept the change in the file suffix like so:

Video Quality Blog Post.014

Zip the folder back into an .ePub file like so:

Video Quality Blog Post.015

Enjoy the success of having reduced the file size of your ePub.

Video Quality Blog Post.016

Test the results in the to confirm that success.

Saturday, November 22, 2014

Using Keynote and Automator for Rapid Screencasting

Automator-based automation in MacOS X 10.10 has a number of important improvements. New Keynote actions for Automator are among them. There are Document Actions (9), Slide Actions (9), Image Actions (2), Chart Actions (1), and Workflow Recipes (6). You can download a Master Installer for these Keynote Actions. There are also a number of Keynote AppleScript commands that can be used.
Among the Document Actions is “Present Slideshow with Narration” which more easily provides the functionality that I described in an earlier post, “
Recording the Self-presenting Presentation.” Thus, rapid screencasting of narrated Keynote presentations is now faster and easier than ever as long as you are OK with choosing only one voice for the entire narration. If not, you’ll need to use the method described in the earlier post if you want to change voices on a slide-by-slide basis. The reason that we’re so interested in screencasting here is that screencasts make excellent instructional videos to include in our eBooks and eTextbooks.
So, how fast is this? The following screencast answers this question better than any number of words.

Download the 1280 X 800 version of this video with a control/right-click
here. Choose “Download linked file as …” naming it “PresentSlideshowWithNarration” or something else that is intuitive for you.

And how easy is this? Here’s a stepwise description of what the set-up process looks like.
Download the example archive. It will have the name “” which you should unpack with a double-click to reveal a folder named, “Narrated-Presentation-Workflow.” The contents of that folder should look like this in list view:

Demo Files

2) Run the installer named “Install” It should let you know exactly what it is about to do and alert you to the fact that this operation will require the approval of an administrative user of that computer.

Install Warning

… followed by a completion message that looks like this:

Install Complete

Note that all the operations cited above are done only once. You will have the capacity of auto narrating any Keynote file containing presenter notes from now on simply by opening a Keynote file that has presenter notes and then selecting “Narrate Frontmost Presentation” from the script menu in MacOS X 10.10 just as depicted in the screencast above.

3) Unpack “” to reveal a folder named “Demo Files” containing a Keynote file named, “Wind Energy in America.key.” We’ll use this to demonstrate how quick and easy this process is once it is installed.

Before turning on your screen recording software (e.g. ScreenFlow), it’s usually a good idea to audition the narration and make any necessary changes to the presenter notes such as adding speech commands (e.g. [[slnc nnn]], and using phonetic misspelling and extra punctuation to achieve a more natural sounding narration.

4) To see how easy this will be in future, simply audition the presentation by opening this demo Keynote slideshow and then selecting “Narrate Frontmost Presentation” from Keynote scripts in the Scripts Menu as follows:

Select  Present From Script Menu

Note that Keynote Scripts are only available when Keynote is frontmost and there is at least one presentation open. Should you wish to change any of the default behaviors of this workflow, simply hold down the Option key while selecting this workflow. This will present the workflow in Automator allowing to to change any or all of the defaults. Here’s how that will appear:

Automator Workflow

Those are the essentials. From this point forward, simply start your screen recording software first and then, with Keynote in the forefront, select the Record Frontmost Presentation from the script menu, sit back, relax and listen to the narrator recite your script. When recording is done, just trim the beginning and end and you are done.

To understand
how this workflow was developed, read all about it on the iworksautomation site. Note the role of commands such as such as [[adv]]. In addition to that, you may also use the techniques described in the earlier post such as phonetic misspelling and the other text-to-speech commands that can make the narrator seem more human. The Apple document, “Techniques for Customizing Synthesized Speech” (2006) is the most complete and recent reference on the subject of improving the realism of synthesized speech that I can find. It was written for API developers, not content developers so you’ll need to read selectively.

In addition to doing screencasts for your own eBooks and eTextbooks, you might also consider student assignments that call for Keynote presentations with presenter notes. Once students have turned those presentations in and let you know which of the many MacOS X voices they prefer, a student authored eBook or eTextbook would be easily assembled from the resulting screencast videos.

Saturday, June 21, 2014

Recording the Self-presenting Presentation

If you watched the screencast video in my last post, "Free Voice Talent ..." you may have noticed that I used a TTS voice for parts of the presentation. What is not evident is the fact that this recorded presentation was entirely automatic, including the human and TTS narration. It was a self-presenting presentation.

Here's how it is done using only ScreenFlow, Keynote, Applescript and Apple's built-in text to speech (TTS) capabilities.

We start by creating a Keynote presentation and making the presenter's notes visible with View > Show Presenter Notes which looks like this:


Next, we create a slide in the Keynote deck using the presenter notes to script the narration for that slide. Repeat until you have laid out all visual and narrative aspects of your message.

At this point, we need to develop an Applescript application that will launch Keynote and cause the presenter notes to be read with a TTS voice. So, go to /Applications/Utilities, open Applescript Editor. Copy and paste in the following script:

property defaultSlideDuraton : 2
property pauseBeforeSpeaking : 1.5
property stoppingStatement : "[[slnc 1000]] Stopping presentation."

tell application "Keynote"
if not (exists document 1) then error number -128

if playing is true then stop the front document

tell document 1
set the slideCount to the count of slides
start from first slide
end tell
repeat with i from 1 to the slideCount
if playing is false then
my speakSlideNotes(stoppingStatement)
error number -128
end if
tell document 1
set thisSlidesPresenterNotes to presenter notes of slide i
end tell
if thisSlidesPresenterNotes is "" then
delay defaultSlideDuraton
if pauseBeforeSpeaking is not 0 then
delay pauseBeforeSpeaking
end if
my speakSlideNotes(thisSlidesPresenterNotes)
end if
if i is slideCount then
exit repeat
if playing is false then
my speakSlideNotes(stoppingStatement)
error number -128
end if
show next
end if
end repeat

tell document 1 to stop
on error errorMessage number errorNumber
if errorNumber is not -128 then
display alert (("ERROR " & errorNumber) as string) message errorMessage
end if
end try
end tell

on speakSlideNotes(thisSlidesPresenterNotes)
if thisSlidesPresenterNotes begins with "[voice:" then
set x to the offset of "]" in thisSlidesPresenterNotes
set textToSay to text from (x + 1) to -1 of thisSlidesPresenterNotes
set thisVoiceName to text 8 thru (x - 1) of thisSlidesPresenterNotes
say textToSay using thisVoiceName
say thisSlidesPresenterNotes -- with waiting until completion
end if
end speakSlideNotes

Save it as a script so that you can use it at any time in the future.

At this point, you could set ScreenFlow to record and then Run the script with your Keynote presentation open and in the forefront. The default system voice will read each slide as it is presented. The presentation will automatically exit after the last slide has been narrated so you can stop the ScreenFlow recording, trim the ends in ScreenFlow and be done.

However and as we discussed in the last post, you may not be satisfied with such a plain vanilla rendition. Thus, we get into a few of the more sophisticated techniques that apply to this kind of work. You should already know about auditioning, using phonetic mis-spelling, punctuation and embedded speech commands to create a more human-sounding rendition of text. If not, review the "Free Voice Talent ..." post for the details.

To these we will add two new techniques: 1) Adjusting for video and animation. 2) Selecting voices on a per slide basis.

Adjusting for video and animation. If your presentation includes a video clip as the screencast referenced here does, you'll need to build in a delay that is equal to the duration of the video. This can be done with the embedded speech command [[slnc nnn]] where nnn is the duration of the embedded video in milliseconds. The following screenshot is of a slide containing a video with a duration of 9 minutes 16.033 seconds. That converts to 556,000 milliseconds. YMMV (Your math may vary).


This also applies to any transitions or animations that you may have included. Simply run the script without recording to audition the slide making adjustments to the placement and duration of the silence command. This command, as you learned from the last post, is also very useful in creating appropriate pauses between paragraphs.

Selecting voices on a per slide basis. Since there is no embedded speech command that enables selecting which voice is operative, we do this via the speakSlideNotes function in the script. This special command must be the first text encountered in the presenter notes (no leading spaces, please). Inserting [voice:Daniel] as the first element in the presenter notes for a slide will cause that voice to be used - no need to change the system default. Note the single (not double) square brackets. This is especially valuable as you may use an alternating male and a female voice to add narrative interest to your screencast. The following screenshot illustrates the use of this special command.


So that's all there is to it. Create a slide deck in Keynote, add presenters notes, audition and adjust the text of the presenter notes with the provided Applescript until the desired presentation with narration is achieved. Then, launch ScreenFlow to record the self-presenting presentation, execute the script, stop recording, trim and export.

Because voice quality and variety is so easily assured with a single take, this could be called Rapid Screencast Development (RSD).