API (3.x)

Introduction

When a user wants to play a video, the user first puts in a media open request. This is the built-in way of player control but it can overridden via the API so that you can use your own control mechanism. This media open request gets sent to the instance’s OpenMedia method which calls PlayX.ResolveProvider to get or guess the provider (YouTube, Vimeo, etc.). The provider converts the arguments into a handler name and its arguments. This handler name and the arguments are sent to the client and are given to the specified handler. The handler builds the HTML, CSS, and JavaScript for the browser and the client entity takes this handler result and uses it to play the media.

Spawning the Player

The player’s entity is named gmod_playx and it can be spawned like any other entity. The only critical piece of information is the entity’s model because it determines the screen position. It is currently not possible to manually define a screen location.

local ent = ents.Create("gmod_playx")
ent:SetModel("models/dav0r/camera.mdl")
ent:SetPos(Vector(-124.8963, 399.7217, 300))
ent:SetAngles(Angle(90, 0, 0))
ent:Spawn()
ent:Activate()

PlayX can be embedded inside a map using Hammer as well.

Playing Media

There are two methods to playing media:

• Using ENT:OpenMedia(), which will automatically find a provider to generate the handler information.
• Using ENT:BeginMedia(), where you have to provide the handler and handler arguments directly.

The normal player control mechanism uses OpenMedia() but for a gamemode, it provides little control of acceptable videos. If you want finer control, you will have to generate the handler manually.

Resolving Providers

PlayX.ResolveProvider() detects the provider (or lets you force one) and returns the provider name (useful if it was detected) and handler table if given a media URI. You can thus check the returned information to see if you want to allow the media. If you do, you could pass the handler information onto ENT:BeginMedia().

local provider, result = PlayX.ResolveProvider(provider, uri, useJW)

-- No provider was detected
if provider == nil then
    return false, result -- Result is a human-readable error message 
end

ent:BeginMedia(result.Handler, result.URI, start, result.ResumeSupported,
               result.LowFramerate, result.HandlerArgs)

In the handler table that is returned is a QueryMetadata() member function that fetches whatever metadata is available for the media. The function takes two arguments: a success callback and a failure callback. The first argument passed to the success callback will be a table contain metadata information. An example member of this metadata information table is Length, which is the length of the media in seconds. This can be used to restrict videos based on length.

ENT:OpenMedia() calls the metadata query function and updates the entity’s metadata with the information using ENT:UpdateMetadata(). If you call ENT:BeginMedia() instead, the metadata information will not be provided to the entity. The following code is the code in OpenMedia() that updates the metadata information.

if result.QueryMetadata then
    result.QueryMetadata(function(data)
        if ValidEntity(self) then self:UpdateMetadata(data) end
    end,
    function(err)
        if ValidEntity(self) then self.OnMetadataError(err) end
    end)
end