Skip to main content

Playlist

This plugin is a list of external media that are pre-defined and setup ahead of time by the world creator.
The playlist has two parts to it: the inspector and the template

Getting Started​

ProTV comes with a pre-made setup for the Playlist plugin. This can be found in the Packages/ArchiTech.ProTV/Samples/Prefabs/Plugins folder. Just drag the Playlist prefab into the scene and assign your desired TV to it. You can adjust various aspects of the playlists as desired.
If you want to have the playlist send the entries to a Queue instead of directly to the TV, just add a Queue to the scene and connect it to the respective slot.

Inspector​

TV References​

  • TV
    The instance of ProTV that this component will interact with and send media to. You will need to insert the desired TV reference (the game object with the TVManager script on it), or if you are using a ready-made prefab, it should already be connected.

  • Queue Optional field where you can specify a Queue plugin object that you wish to make the playlist connect with. If a Queue is provided, then instead of immediately playing the URL a user clicks on, the playlist will forward the desired URL entry into the Queue directly and the Queue then handles the rest.

General Settings​

  • Playlist Storage
    Reference to an alternate component for storing the internal playlist data. This is automatically used when a playlist is more than 100 entries. It is a mitigation to lag that happens when a significant amount of serialized data exists on a single object caused by the unity serializer when visible in the inspector.

  • Preload Queue Amount
    If a Queue reference is connected, this setting defines how many of the playlist entries should be automatically added to the Queue when the instance master first joins the world. This happens only once per world instance.

  • Shuffle Playlist on Load
    Specifies whether to scramble the playlist order when the world loads or not. While the exact shuffle ordering itself isn't synced across users, this is not an issue as the playlist was designed to handle arbitrary ordering from the start.

  • Show Urls in Playlist?
    This toggle makes the playlist template skip displaying the URL for each entry. This is useful if you want to hide what domain/source of the media.

  • Autofill Android Urls
    This toggle enables the autofill feature for dynamically generating alternate urls for the corresponding main url.
    NOTE: Autofill will only happen with this flag enabled and only when clicking Import OR when manually modifying a main URL field.

  • Autofill Format
    Text field that specifies the format for the autofill feature. It does a basic string replace where the text $URL is replaced with the main url value.
    Example: If main url is https://youtu.be/VIDEO_ID and format is https://mysite.tld/?url=$URL, the alternate url would be like https://mysite.tld/?url=https://youtu.be/VIDEO_ID.

Autoplay Options​

  • Autoplay Starts Enabled
    This flag determines whether the playlist Should auto-play be active by default. This is a general setting for whether auto-play logic runs or not.

  • Loop Playlist
    Determines if the playlist should continue playing media from the start of the entries or not once it reaches the end of the list. Having this disabled is useful for playlists that handle show series or a specific sequential list that you might not want to force the users to continue watching once it finishes.

  • Autoplay on Load
    Specifies whether this playlist should attempt to start playing media automatically as soon as the first user joins into a world. This setting only affects the first user to join or if the TV is set to not sync to the owner.

  • Start From Random Entry
    When enabled, the playlist will initialize at some random entry in the list. This is generally paired with the Autoplay on Load option.

  • Enable Autoplay on Interact
    This flag makes the playlist auto-play become enabled implicitly when a user interacts with the playlist. Combine this with Disable Autoplay on Custom Media and Prioritize on Interact to effectively have a 'toggle' between user-entered media and the playlist handling things.

  • Disable Autoplay on Interact
    This flag makes the playlist auto-play become disabled implicitly when a user interacts with the playlist. This is useful for having a playlist run automatically on join, but stop auto-playing when a user picks a video manually.

  • Enable Autoplay on Custom Media
    This flag enables the autoplay flag when a url is successfully loaded that is NOT in the respective playlist. Much less common use, but can help in certain rare scenarios.

  • Disable Autoplay on Custom Media
    This flag disables the autoplay flag when a url is successfully loaded that is NOT in the respective playlist. This pairs well with Enable Autoplay on Interact.

  • Prioritize on Interact
    This flag determines if the playlist should make the attached TV prioritize itself above all other connected playlists. This means that if a TV has multiple playlists associated with it, when a user interacts with a given playlist that has this flag enabled, it will force itself to the front of the line for events from the TV, which makes it able to auto-play before any other playlists might try.

  • Continue From Last Known Entry
    The playlist has an internal value that keeps track of what index it triggered last. If this is enabled, it will use that value to determine which media to play next. Otherwise the playlist will start at the very first entry.

UI Components​

First is the ScrollView component. This is a ScrollRect that is used during the playlist view rendering. This is required for playlist to know how many entries can be rendered within the visible space.

Next up is the two template references, one is the container, the other is the actual template itself. These come with default references out of the box in the prebuilt plugin prefabs. Have a look at the Template Section for more information.

Media Entries​

First is a simple helper button.

  • Update Scene
    This button is for manually trigger the scene to recalculate stuff for the playlist layout and content. For most actions, this is triggered automatically (like while importing a playlist), but for things like modifying the Template content, clicking this button is required to have the layout update itself.

Next, the playlist entries list has two operating modes. These modes are swapped between by the Load Text From File toggle.

  • Manual Entry
    When disabled, the playlist has various buttons for manipulating the contents of the list. The two global buttons are self-explanatory Add Entry and Remove All.
    For each entry there are Main URL, Alt URL, Title and Tags fields as well as an Image input.

  • Importing
    In order to make handling large playlists less painful, ProTV comes with an option to export and import playlists into a tokenized file format.
    When Load Text From File is enabled, the playlist switches to the import mode. All entry manipulation actions are disabled to signify the data is sourced from an asset file, and the global buttons are replaced with a TextAsset field. Put the desired playlist file into this slot and click the Import button to update the contents of the playlist to that of the given file.

  • Exporting
    To handle exporting, there are two convenience buttons to help out:

    • Copy: This button will tokenize the playlist information into a string of text and add it to your clipboard. This will allow you to paste it wherever with ease. Dump it to a text file, share it with a friend, append it to an existing playlist file, etc.

    • Save: This button is only available when the Load Text From File option is unchecked. When you click this, it will open a save dialog where you can choose where to output the playlist content into. Once a location is chosen, the data will export and then the playlist will automatically be updated with the reference to that file in the import TextAsset field.

Playlist File Formatting​

Here's an example of what the tokenized format looks like:

@https://www.youtube.com/watch?v=BHuF3cUf4n8
^https://soundcloud.com/stessieofficial/together
~Stessie - Together
This song is pretty cool.

@https://www.youtube.com/watch?v=gyR9bdqsv_4
#music,melodic,bouncy,upbeat
~Stessie - Close To You
A classy song deserves a classy description.
Don't ya think?

@https://www.youtube.com/watch?v=JWP5e6u4ryE
/Assets/CustomImages/stessie.candy.heart.png
~Stessie ; BLOOD CODE - Candy Heart

The playlist file format is defined as follows:

  • Each playlist entry is defined by the at @ symbol at the start of a line. This is immediately followed by the Main Url for that particular entry.

  • On any of the following lines until the next playlist entry defined by the @ symbol, a single line of any of the following can optionally be provided:

    • An alternate url (see the TV's definition of an alt URL) can be provided and is prefixed by a caret ^ symbol.
      (See first entry in above example)

    • A comma , separated list of tags can be provided and is prefixed by a hash # at the start of the line. If you want to use white spaces near the commas in the file, you can. They are automatically sanitized on import.
      (See second entry in above example)

    • A path to an image can be provided. This must be an image that is within the Assets folder. It is detected by the backslash / prefix and the line should always start with the /Assets/ prefix. If the image is not a Sprite type, it will not be able to be loaded. If it was manually typed, double check for typos. If it was exported, it should already be compatible.
      (See third entry in above example)

    • A custom title can be provided. This can be any text content you want and is prefixed with the tilde ~ symbol. To make the title text multiple lines, each sub

  • If any line after the playlist entry @ line does not start with one of the above tokens (^, #, /, ~) then it will assume that the rest of the content until the next detect playlist entry is part of the entry description and will be greedily added to the description text.

The playlist editor has an auto-detection mechanism for a dropdown selector.
If you want your custom playlist to be selectable from the dropdown, make sure the file extension is .playlist, not .txt.

NOTE​

Tagging​

Playlist tagging is the way to provide extra metadata to an entry without affecting the title. Tags are a comma , separated list of values defined by the world creator for each entry. The actual tag values can be anything you want, but there is a special format use case built-in to facilitate playlist sorting.

Searching​

For playlist searching, there is a Prefab available containing two input fields, one for searching titles and one for searching tags. Searching goes by tags first and then filters by title search.
Searching titles is a simple contains check, but searching by tags has some formatting available to customize the search.
The tag search term will be split by a comma , symbol first. These are considered OR statements. Within each OR statement, the sub-term will then be split by a plus + symbol. These are considered AND statements.
The search is resolved as such:

  • For the current playlist entry...
  • For each of the OR statements, evaluate each AND statement.
    • An AND statement will resolve to true if the searched tag is present in the tag list for the currently evaluating playlist entry.
  • If all AND statements are true, the containing OR statement resolves to true and marks the given playlist entry as visible in the search and moves to the next entry.
  • Otherwise, if any AND statements are false, the OR statement resolves to false and the next OR statement is evaluated.
  • If all OR statements resolve to false, the playlist entry is marked as hidden in the search results.
  • Move to next playlist entry.

Here's an example tag search: movie+horror+2000s,tvshow+comedy+1990s

Another thing you can do is disable tag search GameObject and add some buttons that update the tag search input field with a premade search. This is great for doing specific custom category searches.

Finally, all searching is now done ASYNCHRONOUSLY! No more lag when trying to search for things in large playlists! (though it does make it take more time)

Sorting​

For playlist sorting, there is also a prefab available that comes with some pre-made sort terms. One thing you'll notice is that the sort term syntax is different than the search term syntax.
The syntax is defined as MODE:PREFIX. The MODE is a number from 0 to 5 representing the following:

  • 0 - Reset the sort to the original order that the playlist was in at world load.
  • 1 - Sort the playlist into a random order (aka shuffle)
  • 2 - Sort the playlist by title in ascending unicode order (aka a-z)
  • 3 - Sort the playlist by title in descending unicode order (aka z-a)
  • 4 - Sort the playlist by the given tag value in ascending order
  • 5 - Sort the playlist by the given tag value in descending order

And the :PREFIX is a value that is exclusively used by the 4 and 5 modes. It specifies what "category" aka prefix should be used to sort the tags by. This prefix is optionally part of the tags list and is delimited by a colon : symbol for each desired tag.

So for example, if we wanted to specify a playlist entry has being made in a particular year and belongs to a particular show season, our tags list might look like
year:1994,season:3,1990s,comedy,tvshow,etc

This would enable the entry to be sorted by such a year value. So if multiple entries had a year: prefix, they would be ordered in the playlist based on that value. One with a year of 1992 would be above one with a year of 1994 for mode 4 and inversely for mode 5.

NOTE: When doing a tag search, the prefix is ignored completely and only looks at the value portion if the prefix is present.

Lastly, similar to searching, all sorting is done asynchronously. This means there won't be any lag, but do be aware that when sorting multiple thousands of items, the sorting logic may run for multiple minutes before completing. Work is ongoing to improve this, but for now just be aware of the general slowness of sorting massive playlists.

Customizing the Layout​

You can customize the layout of the playlist quite a bit. The easiest way is to get a playlist prefab in scene, go into its hierarchy to the ScrollView/Viewport/Template object and fiddle around with that. There are only a few things that is checked for in the template:

  • There are 4 GameObjects that are checked for as children of the Template: 1) A GameObjects called Title that contains an attached Text component 2) A GameObjects called Url that contains an attached Text component 3) A GameObjects called Image or Poster that contains an attached Image component 4) A GameObjects that contains an attached Slider component (no name requirements)
  • All of these GameObjects are optional, but at minimum the Title and Slider recommended for a better user experience.

Once you have customized the structure of the template, you can also adjust the layout of the template entirely. The playlist will automatically fill in horizontal space of the viewport with the content.
This can be observed by setting the transform setting Anchors -> Max -> X to 1 / the number of items per row (for example 1/5, or 0.2). Then click Update Scene and you will see the playlist switch to a 5 column layout. You can also adjust the template Height for some layout change as well if you want to display larger entries.

These two Template transform settings Anchors -> Max -> X and Height are the primary controls for getting your desired layout in the playlist.