BLAM3.SDK 3.1.7.25

Blue Lucy SDK

Blue Lucy is a media services integration platform that unifies production and supply chain operations for the media industry. The Blue Lucy .Net SDK provides the coding framework for developers to create their own BLidgets and Plugins for running within the Blue Lucy Workflow Runner. It can also be used to rapidly delevop bespoke integrations directly with the Blue Lucy API.

NuGet Packages

Package	Latest Version
BLAM3.SDK

Documentation

This README provides a quick overview of how to make use of the Blue Lucy .Net SDK. You can check out some sample code on our public GitHub repository for more in depth examples.

Quick Start

[!IMPORTANT] To use the Blue Lucy .Net SDK, you will need to have an active application account on a Blue Lucy system. Please contact support, or your system adminstrator for assistance in setting up an account on your system.

To get started, first add the BLAM3.SDK package to your project by running the following command:

dotnet add package BLAM3.SDK

You can now create a BlamClient using your application credentials and begin searching your media:

// Create a new BlamClient instance using application credentials
var blamClient = new BlamClient(new BlamClientConfig
{
    BlamApiEndpoint = "https://<your>.bluelucy.com/api",
    Username = "<ApplicationUsername>",
    Password = "<ApplicationPassword>"
});

// Search for the first 100 video assets
var results = await blamClient.Search(new SearchQueryInputModel
{
    Query = "type=video",
    Limit = 100
});

// Select first asset from search results
var asset = results.Items.First();

Update asset metadata

// Create a new metadata snapshot updating just the specified values
var snapshot = await blamClient.CreateMetadataSnapshot(new AssetMetadataSnapshotInputModel
{
    AssetId = asset.Id,
    Values = new Dictionary<string, object>
    {
        { "show_name", "Cats on Air" },
        { "vtr", 899223 },
        { "language", "Dutch" },
        { "tx_date", "2033-01-01T15:00:00+01:00" },
        { "for_broadcast", true }
    },
    Merge = true
});

Updating the metadata on an asset creates a new snapshot version. Creating a snapshot with Merge = true will use the current metadata as the snapshot base and replace just the specified values.

Add an asset to a folder

// Search for an existing folder
var folders = await blamClient.Search(new FolderQueryInputModel
{
    Query = "name=Cats on Air",
    Limit = 1,
    Depth = FolderStructureDepth.Contents
});

// Select first folder from search results
var folder = folders.Items.First();

// Attach the asset to the folder
await blamClient.AttachAssetsToFolder(new FolderAssetListInputModel
{
    FolderId = folder.Id,
    AssetIds = [asset.Id]
});

Assets can be added or removed in bulk by providing a collection of asset Ids.

Creating a link to the proxy

// Create a temporary link to the proxy file
var link = await blamClient.CreateStreamToken(new StreamTokenRequestInputModel
{
    Asset = new AssetSelectorInputModel { AssetId = asset.Id, Selector = "Current Version;Browse" },
    MaxAllowedClaims = MaxAllowedClaims.Unlimited,
    ShortUrl = true
});

// Use the url for streaming
var url = link.Url;

Links can be single or multi-use and a sharable with external users or processes (e.g. transcoding into different formats).

Triggering a workflow

// Fetch the list of available workflows
var blueprints = await blamClient.GetWorkflowBlueprints();
var blueprint = blueprints.First(b => b.Name == "Deliver Asset to S3");

// Trigger the selected workflow blueprint
var run = await blamClient.TriggerWorkflow(blueprint.Id, new WorkflowRunInputModel
{
    Name = "Delivery for <Customer>",
    Type = BlidgetDataType.Assets,
    Data = new AssetsIO { AssetIds = [asset.Id] }
});

// Check the current state of the workflow run
var runState = await blamClient.GetWorkflowRun(run.Ids.First());
while (runState.Status != WorkflowRunStatus.Complete)
{
    // ...
}

[!IMPORTANT] Workflows can be highly customised per platform. You should contact your workflow administrator to understand what workflows you have access to on your platform. Access to some workflows can be restricted based on your account group access permissions.

BLidgets

BLidgets are short lived micro-processes executed as steps within a Blue Lucy workflow. A BLidget represents a "unit of work" within a workflow and its scope limited to a single task during execution (e.g. Transcode video, Copy file, Import metadata, Run job etc.)

The Blue Lucy SDK simplifies BLidget creation by providing an inheritable base class which implements the BLidget control flow and handles the passing of messages between the BLidget process and the Workflow runner.

BLidget control flow is broken down into 3 phases; Init, Run and Complete:

// ExampleBlidget implements base class `Blidget` with I/O of type `AssetsIO`
internal class ExampleBlidget : Blidget<AssetsIO, AssetsIO>
{
    private BlamClient _client;
    private ExampleState _runState;

    // INIT PHASE - runs on every blidget run
    protected override void Init(AssetsIO inputData)
    {
        _client = new BlamClient();                 // Initialise BlamClient (inherits configuration from the Workflow runner)
        _runState = GetRunState<ExampleState>();    // Initialise or retrieve the current saved run state
    }
    
    // INIT PAHSE - runs on every blidget run (asynchronous variant of `void Init(...)`)
    // protected override Task InitAsync(AssetsIO inputData)
    // {
    //     // Asynchronous init operations
    // }

    // RUN PHASE - runs on the first BLidget execution only, skipped after waking up from `Waiting` or `Idle`
    protected override async Task<BlidgetOutput<AssetsIO>> RunAsync(AssetsIO inputData)
    {
        // Fetch BLidget configuration value
        var nameTemplate = GetArgument<string>("name_template");

        foreach (var assetId in inputData.AssetIds)
        {
            // Fetch input resources
            var asset = await _client.GetAssetById(assetId);

            // Use interpolator to resolve runtime values
            var name = await Interpolate(nameTemplate, _client, new TemplateData { Asset = asset });

            // Do work ...

            // Add data to the run state
            var job = new Job { Uuid = Guid.NewGuid() };
            _runState.Jobs.Add(job);
                
            // Log Debug message
            LogDebug("Added job with ID: '{id}'", job.Uuid);
        }

        // End process and save current run state; wake again once time has elapsed or receiving a call back
        return Waiting(_runState, pollingIntervalSeconds: PollingInterval.OneHour, message: "Waking again in one hour.");

        // or return Idle(_runState, _runState.Jobs.Select(j => new Callback("jobId", $"{j.Uuid}")), message: "Waking on callback.");
        // or return Complete(inputData);
    }

    // COMPLETE PHASE - called each time the BLidget runs after waking up from `Waiting` or `Idle`
    protected override async Task<BlidgetOutput<AssetsIO>> CompleteAsync(AssetsIO inputData)
    {
        // Loop through jobs and update run state
        foreach (var job in _runState.Jobs)
        {
            // Do work ...

            // Update progress state (used to report progress)
            UpdateProgress(50, "Processed 1 of 2 job(s).");
        }

        // Complete process and pass on output data
        return Complete(inputData, message: $"Processed {_runState.Jobs.Count} job(s).");

        // or return Waiting(_runState, pollingIntervalSeconds: PollingInterval.OneHour, message: "Waking again in one hour.");
        // or return Idle(_runState, _runState.Jobs.Select(j => new Callback("jobId", $"{j.Uuid}")), message: "Waking on callback.");
    }
}

internal class ExampleState
{
    public List<Job> Jobs { get; set; } = [];
}

internal class Job
{
    public Guid Uuid { get; set; }
}

More detailed examples can be found on the samples GitHub repository.

Plugins

Plugins are long running processes which are commonly used for watching for and reacting to internal or external events (e.g. files moving into a folder, a timer elapsing, receiving a message). They can also be used as extensions to the API by implementing additional end points or even act as web server for custom UIs.

Plugins implement the .Net IHostedService and provide two methods for control flow; OnStart and OnStop. Additional services or middleware can also be added using .Net's Dependency Injection allowing developers to create fully featured services within a single Plugin.

There are two possible builder patterns depending on whether a web server is required:

Service Pattern

// ExamplePlugin implements base class `PluginInitialiser`
internal class ExamplePlugin : PluginInitialiser
{
    private async Task CreateHostedService()
    {
        var builder = new HostBuilder()
            .ConfigureAppConfiguration((hostContext, configuration) =>
            {

            })
            .ConfigureServices((hostContext, services) =>
            {   // Configure serivces using dependency injection
                services.AddSingleton<BlamClient>();
                services.AddHostedService<ExamplePluginService>();
            });

        var host = builder
            .Build();

        // Runs hosted service(s)
        await host.RunAsync();
    }

    public override async Task InitAsync()
    {   // Plugin entry point - fetch configuration values here by calling `GetArgumnet`
        await CreateHostedService();
    }
}

// Inject `BlamClient` singleton using dependency injection
internal class ExamplePluginService(BlamClient client) : PluginService
{
    private ExampleState _runState;
    private WorkflowBlueprintViewModel _blueprint;

    // ONSTART PHASE - called when the hosted service first starts on `host.RunAsync()`
    protected override async Task OnStartAsync(CancellationToken cancellationToken)
    {
        _runState = GetRunState<ExampleState>();                        // Initialise or retrieve the current saved run state

        var blueprintId = GetArgument<int>("blueprint_id");             // Fetch BLidget configuration value
        _blueprint = await client.GetWorkflowBlueprint(blueprintId);    // Fetch argument resource

        ProcessWork(cancellationToken);                                 // Begin work
    }

    // ONSTOP PHASE - called when the host application is stopped e.g. SIGTERM received
    protected override Task OnStopAsync(CancellationToken cancellationToken)
    {
        // Clean up steps ...

        return Task.CompletedTask;
    }

    private void ProcessWork(CancellationToken cancellationToken) =>
        Task.Run(async () => await ProcessWorkAsync(cancellationToken), cancellationToken);

    private async Task ProcessWorkAsync(CancellationToken cancellationToken)
    {
        while (!cancellationToken.IsCancellationRequested)
        {
            // Do work ...

            // Save run state during plugin execution
            Save(_runState);

            // Log Debug
            LogDebug("Saved run state.");
        }
    }
}

internal class ExampleState
{
    public List<TrackedItem> Items { get; set; }
}

internal class TrackedItem
{
    public Guid Uuid { get; set; }
}

Web Server Pattern

// ExamplePlugin implements base class `PluginInitialiser`
internal class ExamplePlugin : PluginInitialiser
{
    private async Task CreateWebApp(string baseRoute, int port)
    {
        baseRoute = string.IsNullOrWhiteSpace(baseRoute) ? null : $"/{baseRoute}";

        var builder = WebApplication.CreateBuilder();

        // Configure serivces using dependency injection
        builder.Services.AddSingleton<ExamplePluginService>();
        builder.Services.AddHostedService(p => p.GetService<ExamplePluginService>());
        builder.Logging.ClearProviders();

        var app = builder.Build();

        // Define API endpoints using .Net minimal API
        app.MapGet($"{baseRoute}/hello", () =>
        {
            return "hello, world";
        });

        // Start web server and listen on incoming port
        await app.RunAsync($"http://*:{port}");
    }

    public override async Task InitAsync()
    {   // Plugin entry point - fetch configuration values here by calling `GetArgumnet`
        var baseRoute = GetArgument<string>("base_route");
        var port = GetArgument<int>("port");
        await CreateWebApp(baseRoute.Trim('/'), port);
    }
}

Next steps

To learn more about Blue Lucy, visit the Blue Lucy website.

Samples

• Samples: Samples in this repository serve as a reference for developing BLigdets and Plugins