Introduction
Welcome to Subtitle Engine!
Subtitle Engine is a free, open source, advanced subtitle system intended to improve accessibility for users with auditory-related impairments.
Most recent release: Subtitle Engine 1.01
Features:
- Quick and easy setup
- Global subtitles
- User-specific (local) subtitles
- Subtitles run by the client
- Speaker profiles
- Support for rich text tags
- Creation and modification of speaker profiles during runtime
- Modification of certain settings during a running subtitle via control tags
- Waiting during a subtitle via control tags
- Running multiple sequential subtitles with one command
- Localization
Known Issues:
- Instant subtitles that are longer than one line have a choppy move in animation.
Updates:
Version 1.01:
- Fixed a bug preventing
toggleSubtitles()from functioning properly. - Clarified type formatting on
globalSubtitle(),localSubtitle(),createProfile(), andeditProfile()to indicate the use of a table. - Added error messages relating to localization and the
getString()function. - Removed the incomplete instructions from the
SubtitleEnginemodule, excluding installation instructions.
Documentation
Note: Not all of the documentation has been completed. If you have any questions regarding the use of Subtitle Engine, reply to this post and I will answer your question.
Setup
Initial Setup
- Import Subtitle Engine to your project using this link.
- Move the
SubtitleEnginemodule intogame.ReplicatedStorage. - Move the
SubtitlesScreenGui intogame.StarterGui. - [Optional] Set the
Enabledproperty of theSubtitlesScreenGui tofalse.
You’re done! Setup is that simple.
If you decide to move the SubtitleEngine module into a folder or into some other client accessible location, make sure you update the path to it on the first line of Subtitles.SubtitleController.
Settings
Documentation incomplete.
Updating Versions
Updating your copy of Subtitle Engine is relatively simple, and should take less than a minute.
- Import the newest version of Subtitle Engine to your project using this link.
- Open the
SubtitleEnginemodule for both the old and new versions and locate the settings. - Copy the entire
subtitles.profilestable from the old version and replace it in the new version. - For each setting in the new version, replace the value with the desired value using the old version as a reference. It is not recommended to copy and paste the entire settings list in case new settings were added in the update.
- Delete the old
SubtitleEnginemodule andSubtitlesScreenGui. - Proceed with setup starting at step 2.
That’s it! Enjoy the new version.
Customization
Documentation incomplete.
Running Subtitles
globalSubtitle()
SERVER
se.globalSubtitle(profile : string, text : string, extraOptions : {})
Displays a subtitle for all users.
Example:
local se = require(game:GetService("ReplicatedStorage").SubtitleEngine)
se.globalSubtitle("Debug", "This is a global subtitle using the Debug profile!")
For information on the use of profile, see Speaker Profiles.
For information on the use of extraOptions, see Extra Options.
localSubtitle()
SERVERCLIENT
se.localSubtitle(player : Player, profile : string, text : string, extraOptions : {})
Displays a subtitle for a specific user.
When called from the client, the first argument, for player, may be omitted. However, it must be present if called from the server. Attempting to run the subtitle for another user will result in the subtitle appearing to the client that called it.
Server Example:
local se = require(game:GetService("ReplicatedStorage").SubtitleEngine)
se.localSubtitle(game.Players.Norteous, "Debug", "This is a local subtitle using the Debug profile!")
Replace my username, Norteous, with the username of the player you want to receive the subtitle.
Do note that this server example technically works when called from the client, but the client example shown below is a better option.
Client Example:
local se = require(game:GetService("ReplicatedStorage"):WaitForChild("SubtitleEngine"))
se.localSubtitle("Debug", "This is a local subtitle using the Debug profile!")
For information on the use of profile, see Speaker Profiles.
For information on the use of extraOptions, see Extra Options.
Sequential Subtitles
The text parameter found in globalSubtitle() and localSubtitle() can also be filled with multiple strings by providing them in a table. This will run them separately as sequential subtitles.
Sequential subtitles will wait for the previous subtitle to finish before starting the next one, allowing you to initiate multiple subtitles in the same function without needing to manually adjust wait times between them.
Example:
local se = require(game:GetService("ReplicatedStorage").SubtitleEngine)
se.globalSubtitle("Debug", {
"Example subtitle 1", -- Runs first
"Example subtitle 2", -- Runs second after 1 is completed
"Example subtitle 3" -- Runs third after 1 and 2 are completed
})
toggleSubtitles()
CLIENT
se.toggleSubtitles(state : boolean)
Enables or disables subtitles on the client. Overridden by the forced extra option. Subtitles are enabled by default.
Example:
local se = require(game:GetService("ReplicatedStorage"):WaitForChild("SubtitleEngine"))
se.toggleSubtitles(false) -- Disables subtitles for this client.
se.toggleSubtitles(true) -- Enables subtitles for this client.
Speaker Profiles
All subtitles in Subtitle Engine run on speaker profiles. These profiles determine the subtitle’s appearance as well as how the subtitle is typed.
Creating Profiles
Subtitle profiles can be created in two ways:
- Before the game runs, in the
SubtitleEnginemodule. - During runtime, through the createProfile() function.
It is recommended to use the first method if you plan on reusing the same profile in multiple scripts. However, the second option can be useful for profiles that are only be used once, or cannot be planned ahead of time, like using a player as a speaker.
To create a profile in the SubtitleEngine module, locate the subtitles.profiles table. Once there, you should see a Debug profile as shown below.
subtitles.profiles = {
Debug = { -- Unique name that will be referenced when creating a subtitle
speaker = "Debug", -- Name that will be displayed in the subtitle
speakerColor = Color3.fromRGB(255,100,100), -- The color of the speaker's name
textColor = Color3.fromRGB(255,255,255), -- The color of what is being said
typeDelay = 0.04, -- How long is waited between characters
characterRange = {1,1}, -- How many characters are printed out at once. Chooses randomly within the range provided.
extraWaitTime = 5 -- The extra amount of seconds that the subtitle should be visible after typing is completed. Should always be above 1.
},
}
To create a new profile, simply copy and paste an existing profile, or type it by hand, and modify the options as needed. Note that the profile name must be unique, and should be easy to remember since it is used every time a subtitle is created.
For information on creating profiles during runtime, see createProfile().
Profile Options
| Profile Option | Effect |
|---|---|
| Profile Name | The unique name that will be referenced when creating a subtitle |
| speaker | Name that will be displayed in the subtitle |
| speakerColor | The color of the speaker’s name |
| textColor | The color of what is being said |
| typeDelay | How much time is waited between characters in seconds |
| characterRange | How many characters are printed out at once. Chooses randomly within the range provided. |
| extraWaitTime | The extra amount of seconds that the subtitle should be visible after typing is completed. Should always be above 1, though 5+ is recommended. |
createProfile()
SERVERCLIENT
se.createProfile(profileName : string, data : {})
Documentation incomplete.
editProfile()
SERVERCLIENT
se.editProfile(profileName : string, data : {})
Documentation incomplete.
Rich Text Tags
Subtitle Engine supports most Rich Text Tags, see Roblox’s documentation on them for information on usage. You may encounter issues if you attempt to heavily modify the size of text.
Control Tags
Control tags allow certain profile options to be changed temporarily for a section of a subtitle.
To open a control tag, follow the following format:
<tag = value>
Most control tags need to be closed. To do so, simply add a forward slash (/ ) in front of the tag.
</tag>
Example:
local se = require(game:GetService("ReplicatedStorage").SubtitleEngine)
se.globalSubtitle("Debug", "Hmm<typeDelay = 0.4>....</typeDelay> I wonder what that was.")
typeDelay
<typeDelay = number> string </typeDelay>
Temporarily changes the typeDelay profile option to the number provided until closed.
characterRange
<characterRange = {number, number}> string <characterRange>
Temporarily changes the characterRange profile option to the number range provided until closed.
wait
<wait = number>
Pauses subtitle typing and waits for the number provided in seconds before continuing. The wait control tag cannot be closed.
Extra Options
Write a description
Profile Modification
Documentation incomplete.
forced
Documentation incomplete.
Localization
Write a description
String Tables
Documentation incomplete.
getString()
SERVERCLIENT
se.getString(group : string, index : number)
Documentation incomplete.
setLanguage()
CLIENT
se.setLanguage(language : string)
Documentation incomplete.
License
Subtitle Engine uses the MIT License, meaning you can do essentially anything with it. Although credit for use is always appreciated, it is not required.
