ts-embed

ts-embed is a set of Typescript code & tools to create compacted assets libraries (audio, video, text). It takes some inspiration from the as3 flex [Embed(source="file.png")] syntax.

The advantage of embedding assets is that are included in a single .tse file, and can be accessed faster than if the application has to load every asset individually.

Table of contents

• install
• usage
• loading
• ts-embed API
• grunt-ts-embed task

Install

Bower

bower install ts-embed

Or add it to your bower.json dependencies.

html

<script src="ts-embed.min.js" type="text/javascript"></script>

Usage

To embed assets into our classes, annotate the target properties with the @embed decorator syntax.

class EmbedTestClass {
 
    //helloWorld.txt contents is "HELLO WORLD"
    
    @embed({src:'./resources/helloWorld.txt'});
    helloWorldContents:string;
 
}

Process

Process your source files with the grunt-ts-embed task.

Loading

Load the library and consume it.

Embed parameters

The following table describes the parameters that are available for the embed decorator.

param	required	description
src	true	Specifies the path of the asset to embed, relative to the file containing the @embed statement.
as	false	Specifies the Extractor function to use to recreate the property.
symbol	false	A unique identifier name used to retrieve an embed asset at runtime.
mime	false	Specifies the mime type of the asset. Supported MIME types

@embed{src}

Specifies the path of the asset to embed with a path relative to the file containing the @embed statement.

@embed{as}

By default embedded assets are extracted to its basic representation ( string | Uint8Array ).

Specifying the as parameter let us provide a function (IEmbedExtractor) that will transform this data before it is assigned to the property.

The embed library itself contains this extractors you can use:

• Embed.HTMLImageElement
• Embed.HTMLScriptElement
• Embed.HTMLStyleElement
• Embed.HTMLSourceElement

class EmbedTestClass {
 
    @embed({src:'./resources/image.png'});
    uint8Image:Uint8Array;
    
    @embed({src:'./resources/image.png', as:Embed.HTMLImageElement});
    image:HTMLImageElement;
}

var embedTest = new EmbedTestClass();
console.log( typeof embedTest.uint8Image ); // prints "Uint8Array";
console.log( typeof embedTest.image ); // prints "HTMLImageElement";
 

@embed{custom}

We can also provide custom as functions that implements the IEmbedExtractor interface.

Imagine we need a custom Extractor to get an AudioSource from a loaded mp3 file.

 
// our custom extractor function
function CustomAudioSource( file:IEmbedDiskFile ):AudioBufferSourceNode {
 
    var buffer = (<Uint8Array>file.content).buffer;
    var context = new window.AudioContext();
    var audioSource = context.createBufferSource();
    context.decodeAudioData( buffer, (res)=>{
 
        audioSource.buffer = res;
        audioSource.connect( context.destination );
 
    });
    
    // this is the value actually assigned to the property
    return audioSource;
}
 
class EmbedSoundClass {
 
    @embed({src:'./resources/mp3File.mp3', as:CustomAudioSource});
    mp3AudioSource:AudioBufferSourceNode;
    constructor(){
    	// play the mp3 file
    	this.mp3AudioSource.start(0);
    }
}

@embed{symbol}

The symbol parameter lets us specify a unique asset name to be able to access it at runtime.

class EmbedTest {
    
    @embed({ src:'./resources/logo.png', symbol:'logo' });
    logoImage:HTMLImageElement;
 
}

Latter in our code we can access it with the method:

EmbedUtils.getSymbolAs( symbol:string, as:IEmbedExtractor ):IEmbedFile

var logoImage = EmbedUtils.getSymbolAs('logo', Embed.HTMLImageElement);

@embed{mime}

You can optionally specify a MIME type for the imported asset by using the mimeType parameter. If you do not specify a mimeType parameter, ts-embed makes a best guess about the type of the imported file based on the file extension.

Currently supported MIME types:

app	audio	image	text	video
application/typescript	audio/L24	image/gif	text/css	video/avi
application/ecmascript	audio/mp4	image/jpeg	text/csv	video/mpeg
application/json	audio/mpeg	image/pjpeg	text/html	video/mp4
application/javascript	audio/ogg	image/png	text/javascript	video/ogg
application/octet-stream	audio/opus	image/bmp	text/plain	video/quicktime
application/pdf	audio/vorbis	image/svg+xml	text/rtf	video/webm
application/xml	audio/vnd.wave	image/tiff	text/vcard
application/zip	audio/webm		text/xml
application/gzip

Loading

Loading a library is as simple as creating a new instance of the EmbedLoader class and calling the load method with the source file path.

The load method returns a promise which resolves to a EmbedDisk.

<!-- include the Embed & @embed Directive -->
<script src="ts-embed.min.js"></script>
 
<!-- include the dummy EmbedTest Class -->
<script src="EmbedTest.js"></script>
 
<script>
    // create a new loader
    var loader = new xp.EmbedLoader();
 
    // the load method of the library returns a ES6 promise...
    loader.load('bin/embedOutput.tse').then(function(embedDisk){
 
        // create a new instance of our dummy EmbedTest class
        var embedTest = new EmbedTestClass();
        
        // this logs the contents loaded from the helloWorld.txt file
        console.log( embedTest.helloWorldContents );
        
    });
</script>

grunt-ts-embed

The grunt-ts-embed task will find all assets in our code and generate the corresponding library that we consume with the loader.

A simple configuration example that will find all @embed declarations inside the /src folder and generate the embedOutput.tse inside the out folder.

grunt.initConfig(
    {
        embed: {
            tests: {
                src: ['./src/**/*.ts'],
                out:'./bin/embedOutput.tse'
            }
        }
    }    
);
grunt.loadNpmTasks('grunt-ts-embed');

explorer	firefox	chrome	safari	opera	iphone	ipad	android-chrome	android-browser
⛔ 152.0	✅ 10.0	✅ 14.0	⛔ 5.0.5	⛔ 10.6	✅ 6.0	✅ 6.0	✅ 20.0	✅ 4.2
⛔ 8.0	✅ 11.0	✅ 15.0	⛔ 5.1.0	⛔ 11.0
⛔ 9.0	⛔ 12.0	✅ 16.0	✅ 5.1.1	⛔ 11.6
✅ 13.0	✅ canary
✅ nightly