Skip to main content

Manual Local Testing Toolkit

The gh-pages branch ships a small Python toolkit for engineers who want to manually exercise a local Vylux environment without keeping those helpers in the main application branch.

The toolkit lives under:

tools/manual/

It is intended for local and trusted engineering workflows, not as a production SDK.

Prerequisites​

  • Python 3.11+
  • cryptography, installed automatically with the toolkit, for AES-GCM source tokens
  • boto3 if you want to upload, list, head, or delete objects in RustFS
  • a working .env and, when needed, .env.local

Install the toolkit in editable mode from the repo root:

pip install -e tools/manual

Install the optional RustFS dependency with:

pip install -e 'tools/manual[rustfs]'
If pip and python do not point to the same environment

In most conda and virtualenv workflows, pip and python belong to the same active environment. If yours does not, replace pip ... with python -m pip ....

Environment loading order​

The toolkit loads configuration in this order:

  1. .env
  2. .env.local with override behavior
  3. matching process environment variables with highest priority

This mirrors the common Vylux local-development pattern:

  • .env for container-to-container addresses such as postgres, redis, or otel-collector
  • .env.local for host-to-container overrides such as localhost:5434, localhost:6381, or localhost:9002

Quick start​

From the gh-pages branch root:

pip install -e tools/manual
vylux-manual --help

If you prefer the module form, use:

python -m vylux_manual --help

Use the toolkit like this:

  1. Put the required Vylux settings in .env or .env.local at the repo root.
  2. Install the toolkit once in editable mode.
  3. Run vylux-manual --help to list commands.
  4. Execute one command for the exact slice you want to test: upload, submit a job, inspect job status, or build a signed URL.

The generated vylux-manual command is the primary entry point shown in this guide.

After installation, any shell using the same Python environment can run vylux-manual. The repo root matters for the install command and for the .env files the toolkit loads.

Supported commands​

The toolkit currently supports:

  • uploading objects to the source or media bucket
  • listing objects in the source or media bucket
  • reading object metadata with head
  • deleting objects from the source or media bucket
  • creating audio jobs
  • creating video transcode jobs
  • creating video full jobs
  • fetching job status
  • retrying failed jobs
  • deleting derived media by content hash
  • building signed /img, /original, and /thumb URLs
  • generating reusable AES-GCM source tokens when IMAGE_SOURCE_KEY is configured
  • building /api/key/{id} URLs and Bearer tokens

Common flows​

Upload a source object​

vylux-manual upload source uploads/demo.flac /path/to/demo.flac
vylux-manual upload source uploads/demo.mp4 /path/to/demo.mp4

Create an encrypted audio HLS job​

vylux-manual create-audio a0b1c2d3 uploads/demo.flac --encrypt --waveform

Create an encrypted video transcode job​

vylux-manual create-video-transcode deadbeef uploads/demo.mp4 --encrypt

Check job status​

vylux-manual job-status <job-id>

Delete derived media for a hash​

vylux-manual delete-media deadbeef

For most manual tests, use this sequence:

  1. Upload the source file to the source bucket.
  2. Submit the media job you want to inspect.
  3. Poll with job-status until processing completes.
  4. Generate signed playback or delivery URLs for the resulting assets.

This keeps the toolkit focused on one-off validation and learning flows rather than automation.

After editing the toolkit​

If you change Python code under tools/manual/src/vylux_manual, you usually do not need to rebuild or reinstall anything. Because the package is installed in editable mode, vylux-manual already points at your working tree.

In most cases, the workflow is simply:

vylux-manual --help

Run the command you want to test again after saving your changes.

Re-run the install command only if you change packaging metadata in pyproject.toml, add dependencies, or change console script definitions.

Uninstalling the toolkit​

Remove the toolkit from the current Python environment with:

pip uninstall vylux-manual

If your pip and python do not match, use the interpreter-specific form instead:

python -m pip uninstall vylux-manual

After uninstalling, vylux-manual disappears from that environment. If the command still exists, it usually means another Python environment on your PATH also has it installed.

Signed delivery helpers​

The toolkit can also construct the public-facing routes that your application would normally sign or mint.

Signed image URL​

vylux-manual image-url uploads/sample.png webp --options w320_h180

When IMAGE_SOURCE_KEY is present in .env or .env.local, this command automatically encrypts the source key and uses the encrypted signing domain. Without it, the command retains the plaintext URL behavior.

Generate and save a reusable token separately:

vylux-manual source-token uploads/sample.png
vylux-manual image-url uploads/sample.png webp --options w320_h180 --token '<saved-token>'

Reproduce the documented interoperability vector:

vylux-manual source-token static/forum/recommend-cover.png \
	--nonce 000102030405060708090a0b

--nonce is only for test vectors. Omit it during normal use so the toolkit generates a secure random nonce.

Signed original URL​

vylux-manual original-url uploads/sample.png --token '<saved-token>'

Signed thumbnail URL​

vylux-manual thumb-url videos/mo/movie-2026-04-01/cover.jpg

Key endpoint URL and Bearer token​

vylux-manual key-url <key-id> <content-hash> --ttl 3600

Security notes​

  • Never expose API_KEY, HMAC_SECRET, IMAGE_SOURCE_KEY, or KEY_TOKEN_SECRET to browsers.
  • Treat this toolkit as a trusted local helper, not as a public client.
  • If you share shell history or screenshots, remember that command lines may include sensitive values.