• Introduction
• Reference Documentation
• Function Arguments
• Cue Properties
• Container Styling
• Examples
• Rendering as a Movie

Introduction

This plugin allows you to define a sequence of events to be played back in the selected container element. Typical events might include:

• adding text, images etc at particular x/y coordinates
• fading text in or out by animating opacity
• scrolling text up or down by animating the position
• wiping text in or out by animating the element width

Any elements that can be included in HTML can be included in a title sequence. All styling can be applied using CSS as normal. Many CSS properties can be animated to create fades, wipes, scrolls and zooms.

The examples directory includes some demos to get you started.

The plugin is dual-licensed under the MIT and GPL licences.

Reference Documentation

To use the jquery.titlesequence plugin, you'll need two things:

• a target container element where 'playback' of the title sequence will occur
• a sequence of cue definitions

The sequence is just an array, and each cue is just a Javascript object-literal whose properties define what should happen. For example:

  $('#titles').titleSequence([
      {
          content: "Line one",
          pause: 500
      },
      {
          content: "Line two"
      }
  ]);

The first cue in this sequence will add one line of text ("Line one") to the element with the ID "titles" then, after a 500 millisecond pause, add a second line of text. The position, and appearance of the text can be set by supplying a css property in the cue object:

  {
      content: "Line one",
      css: { top: '100px', left: '180px' },
      pause: 500
  },

You can also supply a class property which allows you to define your styling rules in a CSS file. The content you provide will be wrapped in a <div> and your class will be added to the div. Similarly, you can provide an id to uniquely identify the element for later operations.

To trigger an animation effect, you should supply an animate property which defines new CSS values to animate towards, and a duration property defining how many milliseconds the animation should last.

Function Arguments

The titleSequence() function accepts two arguments:

  $('#titles').titleSequence(sequence, options);

The sequence argument must be an array of cue object-literals. The expected object properties are shown below. The array can also include functions. Each function will be called at the appropriate point in the sequence and will be passed a single argument - an object through which your function can access the supplied options and then call the object's next_cue method to resume processing remaining cues in the sequence.

The options argument allows you to override global aspects of the title sequence. Currently only one option is recognised:

time_factor

This multiplier (which defaults to 1) is applied to each duration and pause value. So for example if you specify a value of 2, the sequence will take twice as long to play back. This is particularly useful if you are attempting to screen-cap frames of the animation for playback as a movie and your hardware is not able to keep up with a higher frame rate.

Cue Properties

When defining a cue, you can provide combinations of the following properties. In the definitions below, the "target element" is either an existing element that matched the selector you provided or if there was no selector but there was content, then the target will be a new element which is created and added.

animate

A collection of CSS properties and their target values in standard object-literal syntax as used by jQuery's css method. Must be used in combination with a duration.

class

This class (or space-separated list of classes) will be applied to the target element.

container

Optional selector for an element within the main container, to which the content for this queue should be added. Useful for grouping elements.

content

Plain text or HTML markup which will be applied as the innerHTML of the target element, replacing any existing content it might have.

css

A collection of CSS properties and their starting values in standard jQuery object-literal syntax.

delete

A jQuery selector - the matching element(s) will be removed from DOM.

duration

Must be used in combination with an animate. Specifies the number of milliseconds that the animation should last.

easing

Must be used in combination with an animate. Specifies the easing function used to control how the speed of the animation changes with time. The only two valid values with default jQuery are 'swing' (the default) and 'linear'. You can install other easing functions (e.g.: jQueryUI includes some).

id

A unique identifier that will be added to the generated wrapper div for you content. This is useful for selecting the element again in a later cue in order to animate it further or to delete it.

no_wait

Must be used in combination with an animate. If set to true, the sequencer will immediately proceed to the next cue without waiting for this animation to end. This allows you to have multiple elements animating at the same time.

pause

Number of millisecond to pause after the animation finishes (if one was defined in this cue) and before moving to the next cue.

selector

A jQuery selector which will be used to identify the target element.

Container Styling

You will probably want to use CSS to style your title sequence container element to allow absolute positioning of title elements; disable word wrapping and hide overflow:

  #titles {
    position: relative;
    width: 640px;
    height: 480px;
    background-color: #000000;
    white-space: nowrap;
    overflow: hidden;
  }

Examples

Example 1 - Simple

A very simple sequence with one piece of text fading in and another wiping in.

Example 2 - Scrolling

A scrolling effect in the style of movie closing credits.

Example 3 - Intro Demo

The introductory demo at the top of this page.

Example 4 - Looping

The final 'cue' in an animation sequence can be a function to replay the sequence.

Rendering as a Movie

As well as publishing your title sequence in a web page, you can also render it to a movie file (e.g.: .mp4 or .avi). The examples directory includes a script called ph-render.js which can be used with PhantomJS (a headless WebKit browser) for this purpose.

You would start by editing ph-render.js to set the URL of the page you want to render as well as the page width and height and possibly the frame rate. Then you would run the script like this (adjust path to wherever you installed PhantomJS):

  /opt/phantomjs/bin/phantomjs ./ph-render.js

This will give you a directory full of PNG images which you can then assemble into an animated GIF using ImageMagick, or into a video using a tool like ffmpeg (AKA: avconv), e.g.:

  avconv -i frames/frame_%04d.png -vcodec libx264 -preset veryslow -qp 0 movie.mp4

(You can choose a different video codec and quality level, but this example produces a top quality file which you can compress later if needed).

Here's an example rendered movie - note it's quite a small frame size so it's best viewed at 1:1 rather than stretched to full screen: movie.avi.

---

Copyright © 2012-2017 Grant McLean