@elacity-js/media-packager

Media upload, processing, progress tracking, and optional NFT minting for the Elacity platform.

Overview

@elacity-js/media-packager orchestrates the full workflow:

1. Create background job
2. Upload thumbnail + media file
3. Track backend transcode/encode progress
4. Optionally mint on-chain

Key Features

• End-to-end upload workflow orchestration
• Workflow-level listener strategy (websocket, polling, or custom)
• Handle-based progress API (IMediaUploadHandle)
• Background job integration
• Browser and Node.js support

Installation

npm install @elacity-js/media-packager @elacity-js/api @elacity-js/contracts @elacity-js/common

For contract adapter support:

npm install @elacity-js/contracts-ethers-adapter ethers

or

npm install @elacity-js/contracts-viem-adapter viem

For Node.js uploads:

npm install form-data

Quick Start

import { ElacityClient } from '@elacity-js/api';
import {
  EthersAdapter,
  EthersAbiEncoder,
  EthersTransactionExecutor,
} from '@elacity-js/contracts-ethers-adapter';
import { MediaUploadService } from '@elacity-js/media-packager';
import { PollingProgressListenerStrategy } from '@elacity-js/media-packager/listeners';
import { ChainId } from '@elacity-js/common';

const apiClient = new ElacityClient({ chainId: ChainId.BASE_MAINNET });
await apiClient.auth.login(address, signature);

const contractRunner = new EthersAdapter(signer);
const contractExecutor = new EthersTransactionExecutor(signer);
const abiEncoder = new EthersAbiEncoder();

const mediaService = new MediaUploadService(
  apiClient,
  contractRunner,
  contractExecutor,
  {
    abiEncoder,
    // listenerStrategy: new PollingProgressListenerStrategy({ pollInterval: 3000 }),
  }
);

const request = await mediaService.createRequest({
  title: 'My Video',
  assetFile: videoFile,
  assetThumbnail: thumbnailFile,
  pricePerSale: 4.99,
  copiesNumber: 100,
  accessMethod: 'buy_once',
  priceCurrency: '0x0000000000000000000000000000000000000000',
  channel: '0x...',
  gateway: '0x...',
  categories: ['Music'],
  previewEnabled: true,
  previewDuration: 30,
  publisher: creatorAddress,
  royalties: [{ identifier: 'A', address: creatorAddress, royalty: 95 }],
});

const handle = await mediaService.execute(request);

handle.onProgress((progress) => {
  console.log(progress.progress, progress.step, progress.caption);
});

handle.startListening();
await handle.waitCompletionOf('generate_metadata');

const mintResult = await mediaService.mint(handle);
console.log(mintResult.tokenId, mintResult.txHash);

Listener Strategy

Progress listener strategy is selected at service construction time and applies to the full workflow handle.

• default: WebSocketProgressListenerStrategy
• listenerStrategy: new PollingProgressListenerStrategy({ pollInterval })
• listenerStrategy: WorkflowProgressListenerStrategy (custom)

Documentation

• Media Package Wiki
• Workflow Architecture
• Listener Strategies

License

See repository root LICENSE.