GitPitch Pro Audio Decks


About

Activate a GitPitch Paid Plan to unlock Pro Cloud Audio.

GitPitch Audio Slide Decks let you enhance traditional slide decks with the spoken word. By activating a voice-over for individual slides and slide fragments, you can unlock brand new ways to SHARE knowledge, TEACH, and deliver TRAINING materials.


Live Audio Slide Deck Example

The best way to appreciate the unique benefits of an audio slide deck is to experience one live. Click on the following screenshot to open a sample audio slide deck in your browser:

AUDIO SLIDE DECK EXAMPLE

When you open this sample deck note the 🎧 headphones icon in the bottom-left corner of your browser window. Position your mouse over this icon to reveal the audio player controls ⏯ to start audio playback for the deck.

If you are viewing this sample slide deck in a browser on your desktop, once playback has started, the deck will automatically advance between slides with the audio playing in sync as each new slide (or slide fragment) is displayed.

If you are viewing this sample slide deck in a browser on a mobile device, the audio will only play as the direct result of user interaction, so you need to click play ⏯ to hear the audio on each new slide.


Audio Deck Activation

By default, audio features are disabled for slide decks. To enable the full set of audio features for your slide deck add the following property to your PITCHME.yaml settings file:


audio-deck : true

When this setting is activated, the standard slideshow menu for your deck is replaced by the audio slide deck player controls icon displayed as 🎧 headphones in the bottom-left corner of each slide. These controls can be used to start and stop audio playback.


Master Audio v Fragment Audio

The main audio file for any slide is referred to as the master audio file. This audio file is guaranteed to play as soon as the corresponding slide is displayed. Master audio files are registered using the @audio markdown widget. This widget must be declared following the delimiter for an audio slide.

Slides are not limited to playing only the one master audio file. Additional files can be registered for audio playback when individual fragments on your slide are displayed. This is a powerful feature that mirrors how people typically deliver real-world presentation content - step-by-step. Working with slide audio fragments is detailed in the following sections of this guide:


Add Slide Master Audio

To activate master audio playback on any slide simply register an audio file using the @audio markdown widget. This widget must be declared directly following the delimiter for the slide. For example:


---
@audio[Greeting](assets/audio/greeting.mp3)

### Hello, World!

The text specified within the square-brackets on the @audio widget is optional. When specified, the text is used to set a custom title for the slide that then appears in the auto-generated table-of-contents for the deck.

The path specified within the round-brackets on the @audio widget is required. Any relative path to a valid audio file can be used. Whatever audio file is indicated on this path is the audio file that will play when the slide is displayed.


Add Slide Code Fragment Audio

The Code Presenting Guide introduces a markdown syntax that allows you to focus-on and step-through code files, snippets, loops, functions, console output, etc. directly on any slide. Each step can optionally display a custom text annotation to provide additional context for your audience.

Slide Code Fragment Audio support lets you replace text-based custom annotations with custom audio playback for individual code-fragments. For example:


---
@audio[Code Intro](assets/audio/intro.mp3)

@code[java zoom-20](src/lib/Utility.java)

@[1-4,zoom-16](assets/audio/java-imports.mp3)
@[9,10,14-18](assets/audio/java-method-args.mp3)

This markdown snippet demonstrates a number of important features:

  1. The snippet declares Slide Master Audio intro.mp3 for playback when the slide is first displayed
  2. The snippet uses a Code Widget to inject a sample Java code file onto the slide
  3. The snippet declares two Slide Code Fragment Audio java-*.mp3 files for playback
  4. These code-fragment audio files are played when the corresponding code fragments are displayed

It does not matter what technique you use to inject code onto your slide - code widgets, code delimiters, fenced-code blocks, etc. The key audio-specific support being demonstrated here is the setting of relative paths to valid audio files within the round-brackets for the code-fragment markers.


Add Slide Snap Fragment Audio

The Snap Layouts Guide introduces a markdown syntax that can be used to control the placement of content on any slide. To activate snap-layouts for any block of markdown you simply wrap the block in opening @snap and closing @snapend tags.

Slide Snap Fragment Audio lets you associate custom audio playback with any block of snapped-content on your slide. When audio is activated, the block is automatically treated as a fragment on the slide. For example:


---
@audio[Deployment](assets/audio/cloud.mp3)

@snap[west span-50]
## Cloud Deployment
@snapend

@snap[east span-50](assets/audio/deploy.mp3)
#### A Bird's Eye View
![DEPLOY](assets/img/deployment.jpg)
@snapend


This markdown snippet demonstrates a number of important features:

  1. The snippet declares Slide Master Audio cloud.mp3 for playback when the slide is first displayed
  2. The snippet declares the Slide Snap Fragment Audio deploy.mp3 file for playback
  3. The snap-fragment audio declaration turns the east snapped-content into a slide fragment
  4. The snap-fragment audio file is played when the corresponding snapped-content is displayed

The key audio-specific support being demonstrated here is the setting of a relative path to a valid audio file within the round-brackets following the opening snap tag for the markdown block.


Add Slide List Fragment Audio

The Markdown List Fragments Guide introduces a markdown syntax for working with list content as slide fragments. This syntax includes support for an optional @note markdown widget that can be used to associate custom speaker-notes with individual list fragments.

Slide List Fragment Audio lets you associate custom audio playback with individual list fragments by extending the functionality of the @note widget. For example:


---
@audio[About](assets/audio/about.mp3)

## What is GitPitch?

@ul
- A modern PowerPoint @note[Markdown, Modular, Versioned](assets/audio/modern.mp3)
- Uniquely adapted for Devs @note[GitHub, GitLab, Bitbucket](assets/audio/developers.mp3)
- On Linux, OSX, and Windows @note[Online, Offline, Export](assets/audio/everywhere.mp3)
@ulend

This markdown snippet demonstrates a number of important features:

  1. The snippet declares Slide Master Audio about.mp3 for playback when the slide is first displayed
  2. The snippet declares Slide List Fragment Audio files for playback using @note on each list item
  3. Each list-fragment audio file is played when the corresponding list-item fragment is displayed

The key audio-specific support being demonstrated here is the setting of a relative path to a valid audio file within the round-brackets for each @note markdown widget used on individual list items.

Note, when activating list-fragment audio, the speaker-note text specified within the square-brackets on the @note widget is optional. For example, @note[](assets/audio/modern.mp3) is valid syntax.


Slides / Fragments without Audio

For audio slide decks it is strongly recommended that each slide and each slide-fragment has its own audio file. This delivers a seamless viewing and listening experience for your audience.

For slides or slide-fragments without audio files associated, by default the slide or fragment content will be displayed for up to 5 seconds in silence before automatically transitioning to the next slide or fragment in the deck. You can override this default no-audio-pause period when activating audio deck features in your PITCHME.yaml. For example:


audio-deck : 8

Here the audio-deck setting has the following effects:

  1. The setting activates audio deck features for your slide deck
  2. And the setting value sets a custom no-audio-pause period measured in seconds.

This no-audio-pause period is a global value, and applies to all slides and slide-fragments where custom audio has not been activated.

If for any reason you want to display a slide or slide-fragment in silence for a period of time that differs fro the global no-audio-pause period, simply record silence for that custom duration, and then register the corresponding silent audio file using standard audio syntax.


Customize Audio Player Controls

The default styling and positioning of the 🎧 headphones icon for audio playback are set with the following built-in CSS style rules:


div.audio-deck-icon {
    color: #E58537;
    position: fixed;
    left: 20px;
    bottom: 20px;
    z-index: 100;
    animation: shake-headphones 1.0s;
    animation-iteration-count: 5;
}

div.audio-deck-controls {
    position: fixed;
    left: 70px;
    bottom: 22px;
    z-index: 99;
}

div.audio-deck-controls > audio {
    opacity: 0.0;
    width: 200px;
    height: 40px;
}

div.audio-deck-controls:hover > audio {
    opacity:1;
    width: 200px;
}

div.audio-deck-icon:hover + div.audio-deck-controls > audio {
    opacity: 1;
}

As a presentation author, you can override these default style rules by activating appropriate custom CSS styles for your slide deck. For example, you could override the default #E58537 color with blue for the 🎧 headphones icon by activating the following custom CSS style rule:


div.audio-deck-icon {
    color: blue;
}

These styling details are provided so you can easily make small tweaks to the audio player controls if needed. Making wholesale changes to these built-in CSS style rules for the 🎧 headphones icon is not recommended unless you perform extensive cross-browser testing before publishing your audio slide deck to the cloud.


Audio File Caching Policies

Audio files used by audio slide decks are cached by the gitpitch.com server for up to 6 hours. This means any changes to the audio files that you push to your upstream repositories on GitHub, GitLab, or Bitbucket will not be heard by your audience until the older versions of those same files expire in the cache.

For this reason, we strongly recommend that you develop your audio slide decks directly within GitPitch Desktop. The Desktop does not cache audio files so you will hear changes to those files immediately. Once work on your audio deck is complete, you can then push your presentation files, including the final versions of your audio files, to your upstream repository. At that point you will be ready to start sharing the link to your new audio slide deck online.


Supported Audio Formats

GitPitch audio slide decks are made possible by HTML5 audio playback support in your browser. The HTML5 standard supports the following audio formats: MP3, WAV, and OGG. But not all Web browsers are capable of playing all of these audio formats.

The following table indicates the current [May, 2019] status of audio support by popular browsers:

Browser MP3 WAV OGG
Internet Explorer YES NO NO
Chrome YES YES YES
Firefox YES YES YES
Safari YES YES NO
Opera YES YES YES

As this table indicates, the only audio format that will reliably play across all browsers is the MP3 format. For this reason, at this time it is strongly recommended that you use MP3 audio files exclusively for your GitPitch audio slide decks. Numerous tools exist that can convert alternate audio formats to MP3.


Audio Recording Tool Recommendations

You can use absolutely any tool to record the audio files for your GitPitch audio slide decks. The only constraint is that the final format of your audio files must meet the conditions documented in the Supported Audio Formats section of this guide.

However, if you are looking for a recommendation, from personal experience I can recommend Audacity. It is a free, easy to use, open-source audio tool. Available on Windows, Mac OSX, and GNU/Linux. You can learn more about Audacity and download the free software here.

Note, GitPitch has no affiliation with the Audacity project. Besides being a big fan :)

There are also numerous online audio recording services, like the Online Voice Recorder. While I have no personal experience using these online tools they do present an alternative if you do not wish to install an audio tool on your desktop.

Tip! For consistent results, always trim silence at the beginning and end for your audio recordings.