FrameTrail - Tutorials - Advanced Use

The FrameTrail player can be initialized directly on your own page in several ways. See the examples folder on GitHub for working implementations of all options below.

Option 1: Adopt an existing `<video>` element

Point FrameTrail at a <video> tag already on your page. FrameTrail wraps it and takes control of playback.

<video id="my-video"
       src="https://example.com/video.mp4"
       style="width: 900px; height: 600px; display: block;"
       playsinline="">
</video>

<script>
document.addEventListener('DOMContentLoaded', function() {
    FrameTrail.init({
        videoElement: '#my-video',
        annotations:  'annotations.json',
        language:     'en-US',
        config:       { autohideControls: true }
    }, 'PlayerLauncher');
});
</script>

Option 2: Explicit container with video URL

Provide an empty <div> container and pass the video URL directly as an init option.

<div id="player" style="width: 900px; height: 600px;"></div>

<script>
document.addEventListener('DOMContentLoaded', function() {
    FrameTrail.init({
        target:      '#player',
        videoSource: 'https://example.com/video.mp4',
        annotations: 'annotations.json',
        language:    'en-US'
    }, 'PlayerLauncher');
});
</script>

Option 3: Data-attribute auto-init

Decorate one or more <video> elements with data-frametrail attributes and call FrameTrail.autoInit() once. Useful when rendering multiple players on a single page.

<video data-frametrail
       data-frametrail-annotations="annotations.json"
       data-frametrail-language="en-US"
       data-frametrail-config='{"autohideControls": true}'
       src="https://example.com/video.mp4"
       playsinline=""></video>

<script>
document.addEventListener('DOMContentLoaded', function() {
    FrameTrail.autoInit();
    // Scope to a specific element: FrameTrail.autoInit(document.getElementById('article'));
});
</script>

Supported data attributes:

data-frametrail — marks the element for auto-initialization
data-frametrail-annotations — URL of a W3C annotations JSON file
data-frametrail-language — language code, e.g. en-US
data-frametrail-config — inline JSON configuration object

Initialization Options Reference

Option	Purpose
`target`	Container selector or DOM element to render the player into
`videoElement`	Selector of an existing `<video>` element to adopt
`videoSource`	Direct video URL (MP4, HLS, YouTube, Vimeo, …)
`annotations`	URL string, array of URLs, or inline W3C annotation objects
`language`	Language code for the UI (e.g. `en-US`, `de-DE`)
`config`	Configuration object — theme, `autohideControls`, layout defaults, etc.
`dataPath`	Base URL for the `_data/` directory (e.g. `'../_data/'` or a CDN URL); auto-detected when omitted
`server`	Base URL for the `_server/` PHP backend; auto-detected when omitted (set `dataPath` without this to force static/CDN mode)
`startID`	ID of the hypervideo to open on load
`contents`	Array of inline hypervideo and annotation data (bypasses `_data/` entirely)
`resources`	Array of inline resource definitions

Using `dataPath` and `server`

When the embedding page is in a subdirectory or on a different host than the FrameTrail installation, set dataPath and server explicitly so requests resolve correctly. If both are omitted, FrameTrail auto-detects by probing the default _server/ path. Providing dataPath without server enables static/CDN mode — read-only access to data without a PHP backend.

// Page is one level below the FrameTrail install:
FrameTrail.init({ dataPath: '../_data/', server: '../_server/', startID: 'abc123' }, 'PlayerLauncher');

// FrameTrail is on a different host entirely:
FrameTrail.init({ dataPath: 'https://frametrail.example.com/_data/', server: 'https://frametrail.example.com/_server/', startID: 'abc123' }, 'PlayerLauncher');

// Static/CDN mode — no PHP backend, read-only (requires CORS: Access-Control-Allow-Origin: *):
FrameTrail.init({ dataPath: 'https://cdn.example.com/project/_data/' }, 'PlayerLauncher');

Inline data — no server required

Pass the complete hypervideo and resource data directly as init options. FrameTrail never touches the _data/ directory, making this approach work in all four storage modes — including in-memory, local folder, and static/CDN mode. Useful for publishing a single self-contained hypervideo.

FrameTrail.init({
    target:  '#container',
    startID: '0',
    config:  { theme: 'dark' },
    contents: [{
        hypervideo: {
            meta:    { name: 'My Video', creator: 'Anonymous',
                       creatorId: 'anon', created: Date.now(), lastchanged: Date.now() },
            config:  { layoutArea: {}, hidden: false },
            clips:   [{ resourceId: 'my-video', duration: 120, start: 0, end: 120 }],
            contents: [], subtitles: {}, globalEvents: {}, customCSS: ''
        },
        annotations: []
    }],
    resources: [{
        label: 'Inline resources',
        type:  'frametrail',
        data:  {
            'my-video': { name: 'Main Video', type: 'youtube', src: 'dQw4w9WgXcQ' }
        }
    }]
}, 'PlayerLauncher');

Tutorials - Advanced Use

Javascript Code Snippets

CSS Code Snippets

Player Initialization

Option 1: Adopt an existing `<video>` element

Option 2: Explicit container with video URL

Option 3: Data-attribute auto-init

Initialization Options Reference

Using `dataPath` and `server`

Inline data — no server required

Tutorials - Advanced Use

Javascript Code Snippets

CSS Code Snippets

Player Initialization

Option 1: Adopt an existing <video> element

Option 2: Explicit container with video URL

Option 3: Data-attribute auto-init

Initialization Options Reference

Using dataPath and server

Inline data — no server required

Option 1: Adopt an existing `<video>` element

Using `dataPath` and `server`