Tracking publisher and player time in Wowza with Wrench

 · 

Pay-per-minute streaming is a simple idea: measure how long a user is connected, then use that duration for billing, reporting, quota checks, or usage analytics. In practice, the important part is not the stopwatch. The important part is connecting streaming events in Wowza Streaming Engine to the rest of your business system.

Wrench is designed for this kind of integration. It can authenticate viewers and publishers, authorize access to individual streams, and run SQL or HTTP hooks during the client lifecycle. That makes it useful not only for protecting playback URLs, but also for building custom metering and accounting workflows around Wowza.

What PPM is for

Pay-per-minute, or PPM, is usually the basis of time-based charging. For a player, this can mean charging a viewer for the number of seconds or minutes spent watching a protected stream. For a publisher, it can mean charging an encoder account, creator, customer, or production team for the time spent broadcasting.

The same mechanism is also useful when no money changes hands. You can use it to record customer usage, enforce monthly included minutes, detect unusually long sessions, reconcile event reports, or feed a dashboard that shows active and historical stream time.

Wrench can track both playback and publishing sessions. The key is that the connecting client must be identified as a user. Once Wrench knows the username behind a player or publisher connection, the PPM monitor can periodically write the elapsed session time into your database.

How Wrench fits into the system

A typical setup has three parts:

  1. Your web application or backend issues a token for a user.
  2. The player or encoder connects to Wowza with that token.
  3. Wrench resolves the token, applies optional authorization rules, and executes lifecycle hooks such as PPM updates.

For database-backed authentication, Wrench can resolve tokens using wrench.token.resolver.sql. For stateless deployments, Wrench can also validate JWT tokens. JWT authentication can be used for both playback and publishing, as long as the token contains the claims Wrench needs, such as the subject username and optionally an encoder flag for publisher tokens.

Publisher-side tracking is especially useful when encoders are not anonymous technical endpoints, but accounts in your own platform. For example, a video platform may let a creator publish a live event, an auction provider may charge sellers by live airtime, or an enterprise system may need to report how long each department broadcasted.

Designing the database

Wrench does not impose a billing schema. Your application owns the database design because billing rules vary widely: prepaid balance, monthly invoicing, free tiers, per-customer rates, per-application rates, minimum billable durations, and grace periods all need different data models.

A sensible starting point is to separate identity, metered sessions, and final disconnect events.

CREATE TABLE wtb_tokens (
  id int NOT NULL PRIMARY KEY AUTO_INCREMENT,
  username varchar(128) NOT NULL,
  token varchar(128) NOT NULL,
  encoder boolean NOT NULL DEFAULT false,
  revoked boolean NOT NULL DEFAULT false,
  ts timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  UNIQUE KEY uq_wtb_tokens_token (token)
);

CREATE TABLE wtb_publisher_minutes (
  id int NOT NULL PRIMARY KEY AUTO_INCREMENT,
  username varchar(128) NOT NULL,
  application varchar(128) NOT NULL,
  session varchar(128) NOT NULL,
  total_seconds decimal(12,3) NOT NULL DEFAULT 0,
  created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  UNIQUE KEY uq_wtb_publisher_minutes_session (username, application, session)
);

CREATE TABLE wtb_disconnects (
  id int NOT NULL PRIMARY KEY AUTO_INCREMENT,
  username varchar(128) NOT NULL,
  session varchar(128) NOT NULL,
  stream varchar(128),
  elapsed_seconds decimal(12,3) NOT NULL,
  created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP
);

The PPM table stores the latest known duration for each session. The disconnect table captures the final duration when the client leaves. In a production billing system, you would normally add foreign keys to your users, customers, products, plans, invoices, or wallet tables. You may also want a rate table so billing is calculated from measured usage instead of being baked into the streaming hook itself.

The Wrench PPM hooks

The core Wrench settings are wrench.monitor.period, wrench.ppm.update.sql, and wrench.ppm.insert.sql.

<Property><Name>wrench.monitor.period</Name><Value>60</Value></Property>
<Property>
  <Name>wrench.ppm.update.sql</Name>
  <Value>update wtb_publisher_minutes set total_seconds=:elapsedtime where username=:username and application=:application and session=:session</Value>
</Property>
<Property>
  <Name>wrench.ppm.insert.sql</Name>
  <Value>insert into wtb_publisher_minutes (username, application, total_seconds, session) values (:username, :application, 0, :session)</Value>
</Property>

On each monitor run, Wrench executes the update query for active clients. If no row is updated, Wrench runs the insert query and future monitor runs update that session. The :elapsedtime parameter is the session duration in seconds. The :session parameter distinguishes separate connections by the same user.

For publishing workflows, enable publisher token purpose checks and return the encoder flag from token resolution. That prevents ordinary playback tokens from being used to publish.

<Property><Name>wrench.publish.encoder.flag.check</Name><Value>true</Value></Property>
<Property>
  <Name>wrench.token.resolver.sql</Name>
  <Value>select username, ts as timestamp, encoder from wtb_tokens where token=:hashedtoken and revoked=false</Value>
</Property>

The same pattern can be adapted for viewers. In that case the token represents a playback user, and the metered time can be written to a viewer usage table instead of a publisher usage table.

Billing and payment integration

PPM tracking should usually be treated as metering, not as the whole billing system. Wrench records the raw fact that a user was connected for a certain amount of time. Your application can then convert those records into invoices, prepaid balance deductions, subscription usage, customer reports, or payment gateway charges.

For prepaid systems, your backend can increase a user’s balance after a successful payment, while Wrench’s dynamic balance checks can decide whether an active session may continue. For invoice-based systems, you can aggregate total_seconds by customer, plan, application, or event at the end of a billing period. For marketplace products, publisher-side metering can be combined with rates, minimum charges, or revenue-share rules.

Keeping these responsibilities separate is important. Wrench integrates Wowza Streaming Engine with your system at the streaming edge. Your backend remains the source of truth for products, customers, payments, and accounting rules.

Example project

A complete publisher-side PPM example is available on GitHub:

streamtoolbox-examples: Wrench pay-per-minute publisher tracking

The example starts MySQL with Docker Compose, configures a Wowza application named ppm, authenticates an FFmpeg publisher using a database token, and verifies that Wrench writes publisher runtime into MySQL through the PPM SQL hooks.

It is intentionally small, but it shows the complete flow: token resolution, publisher authorization, periodic PPM updates, and final disconnect logging. From there, you can replace the sample tables and SQL with the schema and business rules of your own platform.