Metadata-Version: 2.5
Name: texas2step
Version: 2.3.0
Summary: Web-centric throughput, latency, jitter and packet-loss measurement between endpoints.
Project-URL: Homepage, https://github.com/robert-patrick-texas/texas2step
Project-URL: Documentation, https://robert-patrick-texas.github.io/texas2step/
Project-URL: Repository, https://github.com/robert-patrick-texas/texas2step
Project-URL: Issues, https://github.com/robert-patrick-texas/texas2step/issues
Author: Robert Patrick
License-Expression: Apache-2.0
License-File: LICENSE.md
Keywords: jitter,latency,network,packet-loss,speedtest,webrtc
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Telecommunications Industry
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Python: >=3.11
Requires-Dist: aiortc>=1.9
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: uvicorn[standard]>=0.32
Requires-Dist: websockets>=13
Description-Content-Type: text/markdown

# texas2step

**Throughput, latency, jitter and packet loss between endpoints, measured from a web
browser.** Open the page and press Start. texas2step measures the path between you
and the server with multi-stream HTTP transfers, latency probes idle and under load,
and real UDP packet loss over WebRTC, then shows every figure as discrete metrics and
graphs. The same measurements are available as a REST API, a Python CLI, and
server-to-server functions.

![Download in progress](https://raw.githubusercontent.com/robert-patrick-texas/texas2step/main/docs/images/hero-dark.jpg)

Inspired by [speed.cloudflare.com](https://speed.cloudflare.com)
([cloudflare/speedtest](https://github.com/cloudflare/speedtest)), but self-hosted: a
Python server, a dependency-free TypeScript client, and no third-party services, so it
works on air-gapped and internal networks.

## What it measures

| Metric | How | Transport |
|---|---|---|
| **Latency** | 20 keep-alive pings, timed with Resource Timing, server time removed | HTTP |
| **Jitter** | Mean absolute difference between consecutive RTTs | HTTP |
| **Download / upload** | N parallel streams for T seconds, 100 ms timeline, ramp-up excluded | HTTP |
| **One stream** | One stream's download for the same time: what a single file copy gets | HTTP |
| **Latency under load** | Probes every 250 ms on a separate connection during each transfer, graded A+ to F | WebSocket |
| **Packet loss** | Numbered probes on an unreliable data channel, echoed and stamped by the server; each direction's loss and delay apart | UDP (WebRTC) |
| **Stream fairness** | Per-stream rates and Jain's index | HTTP |
| **Call quality** | A G.711 call's MOS (1 to 5) each way, from the ITU-T E-model: delay, and packets lost, late or in bursts | derived |
| **Responsiveness** | Round trips per minute under load, on new connections and the loaded one, as the IETF draft and macOS's `networkQuality` count them | HTTP, WebSocket |
| **Readiness** | Grades for streaming, video calls, reaction time/VDI/SSH and bulk transfers | derived |

Details and definitions: [docs/methodology.md](https://github.com/robert-patrick-texas/texas2step/blob/main/docs/methodology.md). What the scores mean
to the people using a connection: [docs/experience.md](https://github.com/robert-patrick-texas/texas2step/blob/main/docs/experience.md).

![Results](https://raw.githubusercontent.com/robert-patrick-texas/texas2step/main/docs/images/results-light.jpg)

The UI has five views: **Test** (gauge, live link animation, charts, exportable and
shareable results), **Monitor** (continuous UDP probing with a scrolling RTT and loss
trace, to one server or to two at once for a side-by-side comparison, or a voice or video
call's packets scored every 10 seconds), **Diag** (HTTPS,
WebSocket and UDP over IPv4 and IPv6, tried once a second, with your addresses, NAT,
TLS and an event log), **History** (saved runs and trend), and **API** (copy-ready
examples). A site can hide any of them (`page_test`, `page_monitor`, `page_diag`,
`page_history`, `page_api`). Every
chart has a hover readout and a table equivalent.

Visitors pick a theme from the header: Light, Dark, America, Energy, Federal, Military or
Texas, or one that follows the OS. A page-size drop-down beside it (70% to 125%) fits more on smaller screens. Operators can rename the site, add their logo, organization and
support links, show a notice on every page and set the default theme; see
[Branding and themes](https://github.com/robert-patrick-texas/texas2step/blob/main/docs/configuration.md#branding-and-themes).

## Install

On an Ubuntu 26.04 LTS server that already runs nginx, install the Debian package from
the [releases page](https://github.com/robert-patrick-texas/texas2step/releases) and add
one line to your site's `server { }` block:

```bash
sudo apt install ./texas2step-*-amd64.deb        # the package from the releases page
#   in /etc/nginx/sites-available/<your site>:  include snippets/texas2step.conf;
sudo nginx -t && sudo systemctl reload nginx     # → https://www.example.net/texas2step/
```

Or let `texas2step-setup`, which ships next to the `.deb`, check the server first. It
reports what it will change and what you must fix, then writes an install script for
that server. The script installs, reinstalls or upgrades texas2step, merges your
settings into the new template, publishes it through nginx and opens the UDP range:

```bash
sudo ./texas2step-setup --id houston --name "houston.example.net" --location "Houston, TX"
sudo ./texas2step-install.sh                     # after reading it
```

Once installed, `sudo texas2step update` upgrades it to the newest release, and a timer
can do that unattended. On a server without internet access,
`sudo texas2step update --from <directory>` installs a release whose two files you put
there. The [install guide](https://github.com/robert-patrick-texas/texas2step/blob/main/docs/install.md) covers the rest: the setup
tool's options, the optional `/speedtest` address, configuration, the firewall rule for
the UDP test, updates, clearing saved results, cloning a server and removal.

To run it from source instead:

```bash
uv sync && uv run texas2step serve      # http://localhost:8080
```

Building, testing, the docs site and packaging are covered in
[docs/development.md](https://github.com/robert-patrick-texas/texas2step/blob/main/docs/development.md).

## Command line

The CLI runs the same engine from any host toward a texas2step server. The package
installs it as `/usr/bin/texas2step`; elsewhere, `uv tool install texas2step` (or
`pipx install texas2step`) installs it from PyPI.

```bash
texas2step run https://www.example.net/texas2step              # full test, human-readable
texas2step run https://www.example.net/texas2step --json --save
texas2step latency  https://www.example.net/texas2step --count 50
texas2step download https://www.example.net/texas2step --streams 8 --seconds 15
texas2step upload   https://www.example.net/texas2step
texas2step loss     https://www.example.net/texas2step --packets 1000 --interval 5
```

```
client 127.0.0.1 (IPv4, HTTP/1.1)
this computer 127.0.0.1

  Latency               1.85 ms   jitter 0.08 ms   (min 1.63 · p90 2.03 · 20 samples)
  Download         4,893.9 Mbps   peak 5,554.3   (2 streams · loaded -0.8 ms)
  One stream       5,720.1 Mbps   peak 6,167.7   (a single file copy · 117 % of 2 streams)
  Upload           8,681.2 Mbps   peak 11,391.7   (2 streams · loaded +0.1 ms)
  Loss                   0.00 %   (0/200 lost · ↑ 0.00 % ↓ 0.00 % · UDP RTT 1.19 ms · jitter 0.12 ms)
  Call quality          4.4 MOS   excellent   (you hear 4.4 · they hear 4.4 · longest gap ↓ 0 ↑ 0 ms · late ↓ 0.00 % ↑ 0.00 %)
  Responsiveness     28,501 RPM   (↓ 50,014 · ↑ 28,501 · a new connection 1.0 ms idle, 4.7 ms under load)
  Bufferbloat                A+
```

`client` is the address the server sees; `this computer` is the CLI's own on that
connection, before any NAT, with the interface's MAC address on Linux. `--save` stores
both with the result, and `--no-local` leaves them out.

## API

Every primitive is a plain HTTP endpoint (`/api/v1/ping`, `/down`, `/up`, `/ws`,
`/rtc/offer`), and a server can measure toward another server on request:

```bash
curl -o /dev/null 'https://www.example.net/texas2step/api/v1/down?bytes=1000000000'
curl -s -X POST https://dallas.example.net/texas2step/api/v1/measure/full \
     -H 'content-type: application/json' -d '{"target": "https://houston.example.net/texas2step"}'
```

Full reference: [docs/api.md](https://github.com/robert-patrick-texas/texas2step/blob/main/docs/api.md), or `/api/docs` on a running server.

## Several locations

List other texas2step servers in the config and they appear in the header's server
picker. The browser tests the chosen server directly (cross-origin), and each server can
measure the others through the API. See [docs/configuration.md](https://github.com/robert-patrick-texas/texas2step/blob/main/docs/configuration.md).
For servers open to the Internet, see [Access codes](https://github.com/robert-patrick-texas/texas2step/blob/main/docs/access.md).

## Documentation

* [Install](https://github.com/robert-patrick-texas/texas2step/blob/main/docs/install.md): the Ubuntu package, nginx, firewall, upgrades.
* [Configuration](https://github.com/robert-patrick-texas/texas2step/blob/main/docs/configuration.md): every setting.
* [Access codes](https://github.com/robert-patrick-texas/texas2step/blob/main/docs/access.md): servers open to the Internet, a code from the service
  desk, and the desk's tools kept to your networks.
* [Traffic limits](https://github.com/robert-patrick-texas/texas2step/blob/main/docs/traffic.md): a daily and monthly cap on what the tests move,
  for servers whose traffic is billed.
* [Security](https://github.com/robert-patrick-texas/texas2step/blob/main/docs/security.md): the security controls, what each guards against, and
  what is left to the operator.
* [Methodology](https://github.com/robert-patrick-texas/texas2step/blob/main/docs/methodology.md): what is measured, and how.
* [Quality and user experience](https://github.com/robert-patrick-texas/texas2step/blob/main/docs/experience.md): what the call-quality score and
  responsiveness mean to the people using a connection, the adjustments texas2step makes
  to match what they notice, and the sources.
* [API](https://github.com/robert-patrick-texas/texas2step/blob/main/docs/api.md): endpoints and the UDP probe protocol.
* [Development](https://github.com/robert-patrick-texas/texas2step/blob/main/docs/development.md): running from source, tests, docs site, packaging,
  releases.
* [Roadmap](https://github.com/robert-patrick-texas/texas2step/blob/main/docs/roadmap.md): ideas for future work.

The same pages are published at
[robert-patrick-texas.github.io/texas2step](https://robert-patrick-texas.github.io/texas2step/).

## License

Copyright 2026 Robert Patrick. Licensed under the [Apache License 2.0](https://github.com/robert-patrick-texas/texas2step/blob/main/LICENSE.md).
