Kirby field for synchronizing content with audio/video files
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Kirby Subtitler

This plugin is a tweaked structure field allowing you to sync any content you'd like with audio or video files. Suggestions welcome.

Here is a short video preview of what it does.



Please note that this field requires Kirby 2.5.8+. There is no backward compatibility since it makes use of custom modal events introduced with this release.

Put the content of this repo in the site/plugins directory.
The plugin folder must be named subtitler :

|-- site/plugins/
    |-- subtitler/
        |-- fields/
        |-- subtitler.php

Blueprint usage

When using this field, you'll need to set the audio or video file to use. This is done by specifying an (audio / video) field as src.

Any field outputting a single filename can be used as a source (ie. the select field, quickselect, etc.) :

    label: Video file the subtitler field will use
    type: select
    options: videos
    label: My synchronized content
    type: subtitler
    src: videofile
        type: hidden
        type: hidden
        type: hidden
        type: hidden
        label: Content
        type: text (or any kind of field)

3. Notes :

  • This field uses a HTML5 player. It detects by itself whether it's an audio or a video file. Please use widely supported formats (ie. .mp3 / .mp4)

  • The start, startprop, end and endprop fields must be specified within the subtitler fields. They currently cannot be renamed. They can be hidden or you can display them in readonlymode :

    label: Start time (seconds)
    type: text
    readonly: true
    label: Start time (progress)
    type: text
    readonly: true
    label: End time (seconds)
    type: text
    readonly: true
    label: End time (progress)
    type: text
    readonly: true
  • The structure entries can't be manually sorted. The usual sorting option in the blueprint won't cut it either, entries are displayed depending on their starting time.

  • Due to the number of displayed buttons, I didn't intend for this field to be used on a mobile panel. Small screens might run into issues.

  • This field isn't meant to deal with a tremendous amount of subtitles, rather a quick solution for synchronizing a few contents on the fly and allowing to directly link field / page objects. For extensive subtitle work, nothing beats a good old .srt editor.

Front-end usage

The field can be dealt with as a regular structure field. Each entry will have a start, startprop, end and endprop value, formatted like this :

start / end : 364.58745 #(number of seconds)
startprop / endprop : 0.35 #(the progress relative to the file's duration, between 0 and 1)

Please note that in order to retrieve the same order than in the panel, you will need to make sure that the entries are sorted by their start time :

$page->subtitlerfield()->toStructure()->sortBy('start', 'asc');

How to deal with those depends on your use case, but here is a generic way of passing the values as an array in a data-attribute :

<?php if($video = $page->videofile()->toFile()): 
      $values = [];
      foreach($page->subtitlerfield()->toStructure() as $entry) {
          array_push($values, array('start' => $entry->start(), 'end' => $entry->end()));
      } ?>
    <video data-values="<?php echo htmlspecialchars(json_encode($values)); ?>">
        <source src="<?php echo $video->url() ?>" type="<?php echo $video->mime() ?>">
<?php endif; ?>

And getting them on the other side :

var values = JSON.parse(videoElement.getAttribute('data-values'));


Structure field options

The default structure field options should be available ( although many are not useful for the purpose of this field. I haven't tested all of them so issues may occur, please test carefully before using in production. Any help with debugging is welcome !

Translate the buttons text

If your language is missing, you can easily translate the empty state, reset and add texts by adding it to fields/subtitler/translations/translations.php.

To do

  • Fix behaviour on newly added subtitles without reloading the page (the overlap isn't detected)
  • Allow custom colors
  • Try to restore the currentTime on AJAX reloads (localStorage?)


The field translation's method is a copy-paste of the kirby-images' one by medienbaecker.