Getting Started

Prerequisites

You will need the following installed:

  • git (type git --version to check if it is installed)
  • node.js (at least version 14.x - type node -v to check version)

You will also need a Content Fabric Private Key - please check with the Eluvio rep who set up your tenancy.

Fabric Browser

Open your Fabric Browser page with one of the following links:

If you have been set up on our demo network, go to: https://core.demov3.contentfabric.io/#/apps/Eluvio%20Fabric%20Browser/#/

If you have been set up on our production network, go to: https://core.v3.contentfabric.io/#/apps/Eluvio%20Fabric%20Browser/#/

Private Keys

Find and store your Private Key in a safe place

  • Enter the password you chose when first setting up your account
  • Click on the ELUV.IO logo at top left
  • Click on Profile
  • Click on the key icon in the middle of the page to reveal your keys
  • Double-click on the item marked Private: and copy it
  • IMPORTANT: Save in a safe place (a permanent file). Do not share this key. The Content Fabric is designed to be trustless - we do not keep a copy of your key and cannot reset or recover it for you. Until you save a copy of your key somewhere it only exists in your browser's local storage, which can get erased if you choose to wipe your browser history.

elv-utils-js

Download and set up elv-utils-js

  1. If you do not have them already, install git and node.js / npm (recommended minimum version of node.js is 16.x)

  2. Navigate to the directory where you would like to install elv-utils-js and run the following commands:

    3. git clone https://github.com/eluv-io/elv-utils-js
    cd elv-utils-js
    npm install

    At this point, you may see some warnings about package vulnerabilities. As you will only be running local command line scripts (rather than starting a web server that accepts input from the outside world) these are safe to disregard.

Fabric Configuration URL

If you have been set up on the Demo network, the URL is https://demov3.net955210.contentfabric.io/config

If you have been set up on the Production network, the URL is https://main.net955305.contentfabric.io/config

Set Environment Variables

The elv-utils-js scripts use environment variables to supply certain information. These will need to be set whenever you start a new terminal session.

  1. Set FABRIC_CONFIG_URL to your configuration URL, e.g. for production network this would be:

    2. export FABRIC_CONFIG_URL="https://main.net955305.contentfabric.io/config"

  2. Set PRIVATE_KEY to your Content Fabric private key:

    3. export PRIVATE_KEY=0x... (your Content Fabric private key)

  3. If your media files are hosted on AWS S3, also set the following environment variables:

    4. export AWS_REGION=    (your AWS region)
    export AWS_BUCKET=    (your AWS bucket name)
    export AWS_KEY=       (your AWS S3 key - should start with "AK")
    export AWS_SECRET=    (your AWS S3 secret)

Content Type and Library IDs

Look up your Content Type and Library IDs

(Make sure you have set your environment variables first)

  1. Change your current directory to elv-utils-js/utilities:

    2. cd elv-utils-js/utilities

  2. Look up your Content Type IDs with ListTypes.js

    3. node ListTypes.js

    Sample output:

    Get list of content types
     
    Initializing elv-client-js... (config URL: http://localhost:8008/config?qspace=dev&self)
     
    id                               name                                    
    iq__3j9xhdqvzkGvzk5cGSBsD4mk12TG dev-tenant - Channel                    
    iq__3168aeRL4ve6YAE4HX1huEVW6E6T dev-tenant - Eluvio LIVE Drop Event Site
    iq__MeiZ3F266sx1hk3QvccVsLhQKfp  dev-tenant - Eluvio LIVE Marketplace    
    iq__bdQBYaURdXCiHZNkH78B56wQ6eJ  dev-tenant - Eluvio LIVE Tenant         
    iq__4U84NCVvoVH51249dFDobj2ZfZrK dev-tenant - Live Stream                
    iq__2jh5w9vsnE16P2tbd2xNiazcYsbZ dev-tenant - NFT Collection             
    iq__3oGYU8DaVfjsu4GiyALzVvnBcYfU dev-tenant - NFT Template               
    iq__4WQZhWEPmRT8rq5DLSJxBMnRhBAk dev-tenant - Permissions                
    iq__8SLzhEyJWiJ41BPezhswG56MUwL  dev-tenant - Title                      
    iq__TSDVBqGVstjJzhYBXuWTKE2AZaw  dev-tenant - Title Collection           
    iq__2tfLjovW8zMN9Yh6eLmwynX1Cbip dev-tenant - Title Master               
     
    Done.

  3. Copy the IDs for the rows that end with " - Title" and " - Title Master". The first is the Content Type ID for your Mezzanines, the second is the Content Type ID for your Masters.

  4. Look up your Library IDs with ListLibraries.js

    5. node ListLibraries.js --name

    Sample output:

    Get list of libraries
     
    Getting list of libraries...
    Initializing elv-client-js... (config URL: http://localhost:8008/config?qspace=dev&self)
    Found 4 lib(s)
     
    libraryId                        name                         
    ilib3MrFBvGaJeL5rCJeMg2KGPZsVecH dev-tenant - Reports         
    ilib2nLKiR5p2yiGqCNicszxQYyvu9W4 dev-tenant - Properties      
    ilib3fm7YhNrmYBNsgNwFuUso1CRVFw3 dev-tenant - Title Masters   
    ilib29dvmbN91uyXRwcMX88CAs8q2zeT dev-tenant - Title Mezzanines
     
    Done.

  5. Copy the IDs for the rows that end with " - Title Masters" and " - Title Mezzanines". (Note that the order is the reverse of Content Types - the Master library is listed before the Mezzanine library)

Content Admins Access Group

Look up the address of your ‘Content Admins’ Access Group

Run the ListAccessGroups.js script:

node ListAccessGroups.js

Sample output: (you will see your own tenancy name instead of dev-tenant)

List access groups visible to the currently configured private key
 
Initializing elv-client-js... (config URL: http://localhost:8008/config?qspace=dev&self)
 
address                                    name                     
0x8d8780cfa0970a064e247e4a7829f0106b38d7f7 dev-tenant Content Admins
0xde9742280f18724d7b6b2d8bc7f3d96b538bc265 dev-tenant Content Users 
0xce2a975ee73a8091cc7d451ed7c74a1de2739617 dev-tenant Tenant Admins 
 
 
Done.

Copy the address for your Content Admins group.

First Ingest

To test that everything is configured properly, start with a file that is:

  • Short (several minutes or less)
  • Local (i.e. not on S3)
  • Simple (1 video stream and 1 audio stream)

Make sure that the FABRIC_CONFIG_URL and PRIVATE_KEY environment variables are set, and that you are in the elv-utils-js/utilities directory.

At this point, you should have the following information collected for copying and pasting into commands:

  • Content Type and Library ID for Masters
  • Content Type and Library ID for Mezzanines
  • Address of your Content Admins Group

For example, the values collected from the output samples in the previous section are shown below (your values will be different!) Note that Library IDs start with ilib, Content Type IDs start with iq__, and the Access Group address starts with 0x:

Master content type  iq__2tfLjovW8zMN9Yh6eLmwynX1Cbip
Master library       ilib3fm7YhNrmYBNsgNwFuUso1CRVFw3
Mez content type     iq__8SLzhEyJWiJ41BPezhswG56MUwL
Mez library          ilib29dvmbN91uyXRwcMX88CAs8q2zeT
Content Admins group 0x8d8780cfa0970a064e247e4a7829f0106b38d7f7

In the commands that follow, substitute your own values for the items that start with a dollar sign. $MASTER_TYPE and $MEZ_TYPE are the Content Type IDs, $MASTER_LIB and $MEZ_LIB are the Library IDs, and $ACCESS_GROUP_ADDRESS is the "Content Admins" Access Group address. For example, the MasterCreate.js command might look like the following after substitution:

node MasterCreate.js \
  --libraryId ilib3fm7YhNrmYBNsgNwFuUso1CRVFw3 \
  --type iq__2tfLjovW8zMN9Yh6eLmwynX1Cbip \
  --title "Test 1" \
  --files ~/Downloads/Video.mp4

  1. Create the Master:

    2. node MasterCreate.js \
      --libraryId $MASTER_LIB \
      --type $MASTER_TYPE \
      --title "$YOUR_TITLE" \
      --files $PATH_TO_YOUR_FILE

    Sample output:

    Create production master
     
    Initializing elv-client-js... (config URL: http://localhost:8008/config?qspace=dev&self)
    Looking up content type: iq__2tfLjovW8zMN9Yh6eLmwynX1Cbip...
    Video.mp4: 0.0%
    Video.mp4: 100.0%
     
    Production master object created:
      Object ID: iq__4JhZtSENmDu7hTq91LEufzDnDpj3
      Version Hash: hq__6siNFi29bLmTmDAoSJ22t1dbszC7j2Y9KU2YupEuk2HdDr2LuhE5BMmJN6m5sRzJdn7UDpqGDF
     
     
    Done.

  2. Copy the Version Hash output by the MasterCreate.js script. This will need to be substituted in for $MASTER_VERSION_HASH in the next command.

  3. Create the Mezzanine Object (and wait for transcoding to finish)

    4. node MezCreate.js \
      --libraryId $MEZ_LIB \
      --type $MEZ_TYPE \
      --title "$YOUR_TITLE" \
      --masterHash $MASTER_VERSION_HASH \
      --abrProfile ../example-files/abr_profile_no_drm_store_encrypted.json \
      --wait

    Sample output:

    Create Mezzanine offering 'default' for master hq__6siNFi29bLmTmDAoSJ22t1dbszC7j2Y9KU2YupEuk2HdDr2LuhE5BMmJN6m5sRzJdn7UDpqGDF
     
    Reading file elv-utils-js/example-files/abr_profile_no_drm_store_encrypted.json...
    Initializing elv-client-js... (config URL: http://localhost:8008/config?qspace=dev&self)
    Looking up content type: iq__8SLzhEyJWiJ41BPezhswG56MUwL...
    Creating new mezzanine object...
    Starting Mezzanine Job(s)
     
    Library ID: ilib29dvmbN91uyXRwcMX88CAs8q2zeT
    Object ID: iq__i4YaCPa6NTt5747C5XWeoWEPC3K
    Offering: default
    Write Token: tqw__HSRwEN24A4Di7L3fUDX3WdvgE8arN7RyyVdAbY8mG4i9wKhJbc7SbuUVm9o7Yp7311az6wRGpvmwdYoLMCf
    Write Node: http://localhost:8008/
     
    Progress:
    run_state: running
    estimated time left: unknown (not enough progress yet)
    run_state: finished
     
    ABR mezzanine object created:
      Object ID: iq__i4YaCPa6NTt5747C5XWeoWEPC3K
      Version Hash: hq__LmVFMGjnvTRR61J4iPMajq9o4qEt3QnfopncBCUfVx9ggWPzfG9KayeCf5CMHdZj4XnjxiDcy7
     
    Waiting for publishing to finish and new object version to become available...
      new version not available yet, waiting 15 seconds...
    New object version now available
     
    Done.

  4. Copy the Object ID in the output. This will need to be substituted in for $MEZ_OBJECT_ID in the next command.

  5. Grant manage permission for the Mezzanine Object to the your Content Admins group:

    6. node ObjectAddGroupPerm.js \
      --objectId $MEZ_OBJECT_ID \
      --groupAddress $ACCESS_GROUP_ADDRESS \
      --permission manage

    Sample output:

    Add 'manage' permission to iq__i4YaCPa6NTt5747C5XWeoWEPC3K for group 0x8d8780cfa0970a064e247e4a7829f0106b38d7f7
     
    Initializing elv-client-js... (config URL: http://localhost:8008/config?qspace=dev&self)
    Looking up library ID for object iq__i4YaCPa6NTt5747C5XWeoWEPC3K...
    Found library ID: ilib29dvmbN91uyXRwcMX88CAs8q2zeT
    Adding permission: manage...
     
    Done.

    The Object ID you copied in step 4 is the ID of your Mezzanine, and you can use the ID to jump directly to your mezzanine in the Fabric Browser by pasting it into the Find content by ID box at top right of Fabric Browser then pressing Enter or clicking the Search button

    You can also find your Mezzanine by clicking Content on the left sidebar and then on the row for your "Title Mezzanines" library.

    Once you are on the page for your Mezzanine object, click on the Display tab to play it (player will start with sound muted).

    (OPTIONAL) There are two additional steps that are common for most use cases:

  6. Also grant manage permission for the Master Object to your Content Admins group (you will need to copy the Object ID from output of step 1, "Create the Master", and substitute it for $MASTER_OBJECT_ID)

    7. node ObjectAddGroupPerm.js \
      --objectId $MASTER_OBJECT_ID \
      --groupAddress $ACCESS_GROUP_ADDRESS \
      --permission manage

  7. Set the Object Permission on Mezzanine to viewable (you will need to copy the Object ID from output of step 3, "Create the Mezzanine Object", and substitute it for $MEZ_OBJECT_ID)

    8. node ObjectSetPermission.js \
      --objectId $MEZ_OBJECT_ID \
      --permission viewable

    Sample output:

    Set permission on iq__i4YaCPa6NTt5747C5XWeoWEPC3K to viewable
     
    Initializing elv-client-js... (config URL: http://localhost:8008/config?qspace=dev&self)
    Looking up library ID for object iq__i4YaCPa6NTt5747C5XWeoWEPC3K...
    Found library ID: ilib29dvmbN91uyXRwcMX88CAs8q2zeT
    Previous version hash: hq__ErxfDQX4tExvstzb8URyx9WG2BYBrWkAWB66kvzH6Hw3pkQKZzN8PmL6AGAftLyktCcataFxSW
    New version hash: hq__FH1ZgDNyqr2Hj9eFRNNMvSdKfSpU3x5dpPufo2xWbnDKqiXrp9XFV7jDfgoFaXTwTt7aDgVh1t
     
    Done.