Home
v1.0.0+
- Download Showpony's latest release (click "Source code (zip)").
- Put the showpony folder and the story folder on your website.
- Put your story files into story/en/. Your files must be in alphabetical order. You can number them with leading zeroes to make this easy, like: "001.jpg", "002.jpg", "003.jpg", and so on.
- Load showpony.php in a sized div on your website.
<script src="showpony/showpony.php"></script>
You should now have a functional Showpony in your webpage!
For Showpony to work at a basic level, your story files just need to be in order. But you can add quite a bit of useful info into filenames, and in some cases it's pretty much essential.
By putting data into your filenames, you can:
- Have them go live at specific dates (and be hidden until then)
- Display a title in the menu
- Scrub video and audio properly in the menu
- Mix media (like text and video) effectively, with each taking up a reasonable amount of the scrub area in the menu
001 The Adventure Begins.jpg // This will work
001 2019-01-01 {The Adventure Begins} 20s 0q.jpg // But this has a lot more functionality
Release dates can look like any of the following:
// 2019, January, 1st
2019-01-01.jpg
19-01-01.jpg
19-1-1.jpg
19-1.jpg
2019-01-01-09-30.jpg // Still January 1st, but at 9:30 AM
2019-01-01-09-30-01.jpg // Still January 1st at 9:30 AM, but 1 second in
You can put them anywhere in your filename.
Note that the times you put in will be based on UTC and not on your local timezone.
If the file shouldn't be live yet, it will be prepended with a "" and be hidden from users. Once it's time for it to go live, the "" will be removed and your audience will be able to view it.
Titles have to be between brackets.
19-12-25 {Christmas Special}.vn
These will show up as titles for your story file, at the top of Showpony.
Durations are integers and decimals denoted by an "s" at the end of them. They're the length of your file in seconds.
0001 30s.html // 30 seconds long
0002 40.25s.html // 40.25 seconds long
This is essential to add for videos and audio to display their times correctly, and will make scrubbing between files of different media much smoother.
If you have different levels of quality for the same file (such as 480p, 720p, 1080p...), you can denote a quality value with "q" and an integer:
001 q0.mp4
001 q1.mp4
001 q2.mp4
The higher the number after q, the higher the level of quality.
If you have multiple levels of quality, one of them must always be 0.
You can set the names for each tier of quality in settings.php in QUALITY_NAMES. These names will show up in the menu's quality popup.
You can have multiple quality levels for just a few files in your story. For example, maybe you want your video cutscenes to have multiple quality levels, but your Visual Novel portions to all be the same level of quality.
Everything else in the filename must stay exactly the same if you use this method- date to go live, title, etc.
~ appears before files that aren't ready to go live and keeps users from directly accessing that file. When it's time for that file to go live, Showpony will automatically remove the ~.
Even if users try to access files that start with ~ directly, they'll be met with a 404 error (this is why the .htaccess file is important!). If they try to see a list of files by going to a directory, they will be blocked.
~ will only be automatically applied and removed if the file has a valid date in the name. You can manually apply and remove it instead if you don't use properly formatted dates.
You can also add ~ to files in the subtitles and resources folders. If you unhide a Kinetic Novel or Text file, and it needs a file from resources, it'll automatically unhide it. Subtitles will also automatically be unhidden.
You can still access ~ files from the server side, and using the admin console you can still access them.
The only catch: if a folder is publicly accessible (no ~ at the start), and you go to the directory, it will show as 403, not 404. This is important: you need to make sure folders are hidden if you want nobody to discover that the folder exists. Otherwise, the 403 will confirm that the folder exists.
You can change this character by replacing it in .htaccess and in settings.php with HIDING_CHAR.
You can put your files into folders, but the folders must be in alphabetical order and the files inside must be in alphabetical order for this to work correctly.
Folders are handy for organization, but folders can also have titles:
c1 {Chapter 1}/
If you have a title on a folder, that title will be passed along to the Showpony. So let's say you have a file in a path like so:
en/c1 {Chapter 1}/001.txt
Your title will be "Chapter 1" for the file, and any other files in the folder will have the same title. If a folder and contained file have a title:
en/c1 {Chapter 1}/001 {The Adventure Begins}.txt
They'll be combined and separated by a colon, like so: "Chapter 1: The Adventure Begins".
This allows you to specify section titles and chapter titles, which can be really helpful for user scrubbing through your story!
You can have a file stay at the end, past all other files (even as new ones are unhidden), by naming it "end (Credits) 10.ext". This can let you have credits files and the like.
Assuming you start with dates or numbers with leading zeroes, the file starting with letters will always be at the very end of the set.
Not all characters are supported in Windows (dagnabit Windows!). If you want to display certain characters in your story's titles, you'll have to use these codes instead:
[dq] "
[c] :
[bs] \
[fs] /
[b] |
[a] *
[gt] >
[lt] <
You can remove module files you won't be using by going to showpony/modules/. Unused modules won't be loaded into Showpony- only loaded ones- so you don't have much to worry about it.
You can also remove admin.php and get-hidden-file.php if you don't want to support admin settings.
You can add a cover by putting a file called cover.jpg in the story folder. This image will show up on initial load behind the menu and disappear when the user starts interacting with the Showpony.
I recommend you enable PHP's intl extension. If it's not enabled, Showpony will still work, but in the settings dropdowns languages and subtitles won't be written out in their full names: they'll be "en" instead of "English", for example.
The Showpony will be created as a JS object, camel-cased with dashes removed. It's based on the last folder in the path you give it to search for the story in. If your path is just the default- story- your Showpony object will be called story. Otherwise, look below for examples in the case of subfolders:
Examples
Path: story/comic -> Object: comic
Path: story/video-series -> Object: videoSeries
Showpony's window lets off the following event listeners. You'll have to check them on showponyObject.window:
'play': We've unpaused.
'pause': We've paused.
'timeupdate': We've moved in the story at least a tiny bit. Contains detail:{file,time} that can be checked. (Note that file will be 0 for the first file, because this is computer counting. You may have to add 1 to this value before presenting it to users.)
'end': We've hit the end of the story.
'fullscreenEnter': Showpony's entered fullscreen.
'fullscreenExit': Showpony's exited fullscreen.
You can see the functions on the Showpony object by going to the demo page and looking through the attributes below.
If you'd like more details here or that would be helpful, let me know! I figure seeing it in context and in action would be more helpful though.
Used to go forward. It's functionality will differ for different modules, but it will always take the user forward a bit, whether it's to the next page in a comic, an upcoming time in a video, or the next keyframe in a visual novel.
story.progress();
Used to go back. It's functionality will differ for different modules, but it will always take the user a bit back in time, whether it's to the previous page in a comic, a recent time in a video, or the previous keyframe in a visual novel.
story.regress();
Set to a time in your overall story.
story.time = 60;
Set to a file in your overall story. Starts at 0.
story.file = 7;
Set to true or false, or use 'toggle'.
story.fullscreen = true;
Set to the shortname of supported subtitles.
story.subtitles = 'en'; // Use English subtitles
story.subtitles = 'en-cc'; // Use English closed captions
story.subtitles = null; // Turn off subtitles
Set to the shortname of a supported language.
story.language = 'en'; // Use English files
story.language = 'es'; // Use Spanish files
Pause and unpause Showpony.
story.paused = false; // Plays the Showpony
story.paused = true; // Pauses the Showpony
story.paused = 'toggle'; // Plays if paused, and pauses if playing the Showpony
If you want to override Showpony's base styles without editing the base files, create a file callsed styles.css inside of your main story folder. You can add any styles in there that you may want.
You can also add showpony queries to this file. These queries check the size of your Showpony window rather than the size of the overall browser window to make changes.
To make these queries, prepend them with @showpony instead of @media:
@showpony (max-width:600px){
.m-vn-textbox:not(.name){
left:0;
right:0;
bottom:0;
min-height:2.5em;
}
}
We will be adding support for more @showpony queries over time, but make sure that what you're trying to accomplish wouldn't be better solved by using a regular @media query before trying an @showpony query.
Files go into the subtitles folder, and into separate language folders like so:
subtitles/en/ subtitles/es/
If you want a subtitles folder to be for Closed Captions, end it with -cc, and it will be recognized in Showpony:
subtitles/en-cc/ subtitles/zh-Hans-cc/
All subtitle files must be:
- 4 numbers long with leading zeroes
- vtt extension
0001.vtt 0002.vtt 0038.vtt
Different modules handle subtitles different ways. Go to wiki pages for those modules to see how they handle subtitles.
You can hide subtitle files using ~, and they will be unhidden when the file its connected to is unhidden. So once the 5th file is unhidden in a story, 0005.vtt will be unhidden.
showpony/settings.php has some useful settings for you to set up. (wow, what a great sentence)
Below are the defaults.
const DEFAULT_PATH = 'story/'; // The path to the files we'll play
const DEFAULT_LANGUAGE = 'en'; // If a language isn't set by the user, assume this one
const DEFAULT_SUBTITLES = null; // If subtitles aren't set by the user, assume this one
const DEFAULT_QUALITY = 1; // If quality level isn't set by the user, assume this one
const DEFAULT_FILE_DURATION = 10; // How long files without a duration in their filename will be assumed to be
const DEFAULT_START = 0; // Where we'll start in the Showpony by default
const DEFAULT_PROGRESS = 'time'; // How to display progress in the menu. 'file', 'time', or 'percent'
const DEFAULT_DIRECTION = 'left-to-right'; // 'left-to-right' or 'right-to-left'
const HIDING_CHAR = '~'; // Start a filename with this char to hide it. Change in .htaccess too, to block direct URL access
const PRELOAD_BYTES = .5 * 1048576; // How many file bytes to preload
const RELEASE_DATES = 1; // How many upcoming files to show release dates for
const DEBUG = false; // Passes PHP notices and errors to Showpony's creation event
date_default_timezone_set('UTC'); // The timezone we're reading times in
const QUALITY_NAMES = [
'480p' // 0$
,'720p' // 1$
,'1080p' // 2$
,'4K' // 3$
];
// What modules to load for what file types
const FILE_GET_MODULE = [
'mime:text' => 'text'
,'mime:image' => 'image'
,'ext:svg' => 'image' // Not all servers recognize SVGs as images by default
,'mime:audio' => 'audio'
,'mime:video' => 'video'
,'ext:vn' => 'visualNovel'
,'mime:application' => null
];
// This function is run on a new file's release. THIS WILL ONLY WORK IF THE FILE IS UNHIDDEN BY ITS DATE, not if a file's just manually added.
function NEW_RELEASE($number, $info){
// $number: the file's number
// $info: an array of the file's info, same layout as passed to Showpony JS
}Most of these are pretty straightforward (let me know if they're not), but a few deserve special discussion:
This associative array determines which modules to use for which file types.
File types available are partial MIME types, full MIME types, or extensions. It checks for a match to files in these order: extension > full MIME > partial MIME > 'default'.
MIME types are information on the file type. You can pass a partial or complete MIME type- partial being everything before the slash in a type like "image/jpeg" and full being the whole "image/jpeg" bit.
The module's name here will be the name of the module's folder. If you set a file type's module to null you'll prevent that file from being opened.
This function is meant to let you send emails, push notifications, etc when a new part of your story is released.
Note that this will only trigger if a file is unhidden by date, and at that time. If you have a file scheduled to go live at 1 PM, and nobody checks your website until 2 PM, NEW_RELEASE() won't trigger until 2 PM.
