AudionAudion
ENDERU

Audion Traffic Counter — user guide

USER_GUIDE_EN.md

Audion Traffic Counter — user guide

Contents

The program counts vehicles in recordings of ordinary cameras: how many cars, buses, trucks and motorcycles made each movement. Counting lines are drawn on the frame, the recording goes into a queue, and the result is a table by movement and class plus a file of events, one per vehicle.

The count runs on your machine. Recordings are not sent anywhere.

What you need

through TensorRT a half-hour recording of 640x480 takes about five minutes on an RTX 5070. An NVIDIA GTX card counts through PyTorch, several times slower. Without NVIDIA the program counts through DirectML on any DirectX 12 video card (Intel, AMD): on integrated Intel graphics a half-hour recording takes about an hour and a half.

about 15 GB on a machine with an RTX card (PyTorch and TensorRT are 3 GB downloads each).

Starting and installing

Unpack the program folder anywhere and start Start.exe. The program is portable: it keeps everything of its own in this folder. One thing goes into Windows: the Microsoft Visual C++ Redistributable PyTorch needs - and only when it is not there. The list of recordings, the lines and the results can be kept apart from the program, in a work folder - see "SETTINGS".

At the first start the counting engine is not there yet: the window opens the SETUP section by itself and asks whether to install it. The question says that without the engine the program does not count, how much comes for this machine (about 15 GB of disk on an RTX card, about 5 GB without an NVIDIA card), and what will be installed into Windows. Nothing is downloaded until you answer DOWNLOAD AND INSTALL; after a refusal the button INSTALL WHAT IS NEEDED asks the same:

  1. The THIS MACHINE card shows the video cards and what follows from them.
  2. Press INSTALL WHAT IS NEEDED and confirm. Green marks exactly what this machine lacks:

its own Python, PyTorch for your video card, TensorRT for an RTX card, the detection library, FFmpeg. Before them the program looks whether Windows has the Microsoft Visual C++ Redistributable and, when it has not, installs it with winget - Windows asks for the administrator's consent.

  1. The installation is shown in the journal (the JOURNAL button, bottom right). It can

be stopped with STOP and started again.

  1. When everything is installed, the program removes the downloaded installation files by

itself: on a machine with an RTX card the program folder then takes about 11.5 GB.

The installed folder can be carried whole to another machine with an NVIDIA card: nothing has to be installed again. On another video card the first count starts half a minute later - the program builds its fast engine for that card. On a machine without an NVIDIA card open SETUP: it shows in green what that machine lacks.

The other buttons of the section repair one part. TENSORRT is the fast count on an RTX card: on a machine with one it is installed together with the environment. DIRECTML and OPENVINO are spare ways to count; install OPENVINO only as the last resort: it is the least reliable for a queue of many recordings.

SETUP holds only what is installed for the counting engine. How the program itself works is chosen in the SETTINGS section.

If the NVIDIA driver is too old, the section says so and asks you to update it.

The project file

The program keeps the lines of every recording in its own folder and, as a second copy, in the project file audion-traffic-counter.json. By default it lies in the folder of the videos themselves. A recording is known there by the fingerprint of its file, not by its name, so the placement comes back by itself: move the folder of recordings to another machine, install the program anew, add a recording again - the lines are there.

The PROJECT FILE card of SETTINGS chooses the place: BESIDE THE RECORDINGS or IN THE USER'S FOLDER - one file for all recordings in the chosen folder. The second is for recordings that lie on a read-only disc or in somebody else's folder.

How the window is laid out

RESULTS, TRAINING. Under the name of each is its state: how many recordings, how many of them without lines, what is queued, what names the kinds.

which becomes STOP while a count runs. SETUP is what is installed for the counting engine (Python, PyTorch, the model, FFmpeg); SETTINGS is how the program itself works.

RECORDINGS

ADD FILES… and ADD A FOLDER… put videos on the list. The files stay where they are: the program remembers the path and copies nothing.

The list takes .avi, .mp4, .mov, .mkv, .mts, .m2ts, .mpg, .wmv, .ts and .webm files; ADD A FOLDER passes by files with other extensions. The codecs are the usual ones: H.264, H.265, AV1, MJPEG, MPEG-2, MPEG-4. If a recording of a rare format shows in CAMERA and its count "failed", the counting engine could not read it: re-encode it to MP4 (H.264). Make an interlaced recording (DV 720x576) progressive before it is counted.

A row shows the frame size and the length, whether the lines are placed, and how many times the recording was counted. The mark on the left takes the recording into the queue. A click on a row chooses the recording for CAMERA and RESULTS.

A new recording comes without lines.

CAMERA: lines, gates, zones

On the left is the video of the chosen recording, on the right its placement. Every recording has a placement of its own: an edit on one recording does not change the others.

A line

Take the LINE tool, press on the frame and drag the line across the road.

middle of the line. The move of the mouse sets it: drawn bottom to top - those going right are counted, top to bottom - left, right to left - away from the camera, left to right - towards the camera.

as well, as a number of its own.

the whole flow before a fork, for example, with a line on each ramp behind it. The numbers of such a line are shown in the results and left out of the TOTAL row - the same vehicles would be counted twice otherwise.

Put a line where vehicles are large and do not hide one another: not on a stop line, not behind a pole and not at the very edge of the frame. A vehicle is counted once per pass.

A gate

Gates are for an intersection and a roundabout, when it matters from where and to where a vehicle went. With the GATE tool draw a line across every branch - over its entry and exit lanes together - and name the branch. From the gates the program pairs the entry and the exit of one vehicle into a manoeuvre "A → B": left, straight on, right, a U-turn.

A straight road needs no gates - lines are enough.

A zone

Far vehicles take a few pixels, and the program misses them. With the ZONE tool draw a rectangle around the far part of the frame and choose the enlargement, ×2 or ×3: the zone is counted on its own, enlarged. A line that lies in the zone is given to it (the "Zone" switch in the row of the line). Enlargement slows the count down.

Editing and going through the recordings

a zone by a corner or an edge. Delete removes what is chosen.

recording. Going to a neighbouring recording saves the edits by itself; so do closing the program and starting a count.

list. Handy for recordings of one shoot from one spot: copy and, if the frame has shifted, nudge the ends.

This is how all recordings are gone through in a row: draw the lines, go to the next one.

COUNT

At the top left is THE COUNT AS IT GOES: how many vehicles are counted so far, the speed and the time left. When several recordings are counted at once, each has a row of numbers of its own. On the right are THIS MACHINE and HOW TO COUNT, below them the QUEUE; a long queue scrolls by itself, the rest stays where it is.

THIS MACHINE is what the count runs on: the processor, the memory, the video card, its driver, Windows. The ENGINE tile shows what the program counts with: while nothing is counted - the choice of "Count on" (AUTO); during a count - what the recording is really counted on, TensorRT for example.

The HOW TO COUNT card:

larger model sees far and partly hidden vehicles better. The weights are downloaded by themselves at the first count.

CUDA), otherwise DirectML. What the machine has not got is dimmed.

How many recordings to count at once, the threads and the priority of the count are in the SETTINGS section.

TRIAL RUN counts the first minute of the chosen recording and saves frames with boxes and lines. Look at them before a count that takes hours: the boxes must stand on vehicles, the lines across the flows.

COUNT counts all marked recordings in order - several at once on an NVIDIA card, and then every recording has a row of numbers of its own in THE COUNT AS IT GOES. The queue can be left for the night:

count "failed", and the journal says why. When no more than a second (or one per cent of the recording) is missing at the end, the run is kept and marked in RESULTS as not read to the end;

reached yet leaves it or joins it;

still put it to sleep);

RESULTS

Every count of a recording is kept as a run of its own and does not replace the earlier ones.

it, the manoeuvres through gates. The last row, TOTAL, is the number of vehicles of the whole recording: the sum over all movements for each class and for all of them, like the total column of a survey sheet. Check lines are left out of it; of a gate only the entry is counted.

has moved. The last row is the TOTAL of every run.

While a count runs, the number of vehicles so far stands in the THE COUNT AS IT GOES card of COUNT - the TOTAL tile before the tiles of the movements.

A run counted by an earlier version of the program has no TOTAL row: count the recording again.

class, line. RUN FOLDER opens the folder with the files.

The report: Word and Excel files

The REPORT card at the top of the section writes the result into a folder you name:

There are two files, both written for a transport engineer. The Word document begins with the main figures (how many recordings, vehicles, cars, buses, trucks) and an overview with the volume in vehicles an hour; then every recording has a page of its own: the number of vehicles, the volume and the composition of the flow in percent, a frame with the counting sections and the numbers of the directions, the table by direction, the total. The Excel sheet holds the same numbers as tables: the sheet "Overview" (by direction, with the volume and the composition), the sheet "By 15 minutes" (the volume by interval from the start of the recording, with a filter), the sheet "Recordings", and the sheet "Service" - by what and when every recording was processed, for whoever maintains the program. The volume is the count of the recording brought to an hour: a recording of 15 minutes is multiplied by four. There are no passenger-car equivalents in the report. The name of a file carries the date and the time, so a new report does not replace an earlier one.

A recording whose numbers are not to be trusted without a check is marked "check", with the reason beside it:

took for cars. It happens on a camera unlike those the model was taught on. The number of vehicles is right then; their division into cars, buses and trucks is not to be trusted on such a recording.

When recordings were counted by hand (see below), the report holds the comparison as well.

Checking against a manual count

If the recording was once counted by hand, the program shows the difference in percent beside every number. Put a file reference\<recording name>\<recording name>.json, where the recording name is the name of its file without the extension (for DSCN0002.AVI it is reference\DSCN0002\DSCN0002.json):

{
  "engine_classes": { "car": [0], "bus": [1], "truck": [2, 3] },
  "counts": {
    "N1": [120, 4, 9, 2],
    "N2": [87, 2, 5, 0]
  }
}

counts holds a row of numbers per movement, in the order of the columns of your sheet. engine_classes says which columns add up into the classes of the program: car, bus, truck.

TRAINING

The detector confuses the kinds of vehicles - cars, trucks, buses: it calls a route van now a bus, now a truck, and a long truck a bus. The TRAINING section names them more exactly.

The MODEL OF KINDS card - what names the kinds in a count:

program (system_core\kinds), so nothing has to be installed or taught for it. Which model is the default one is written in config\classes_default.json; should its file be missing, the detector names the kinds, and the tooltip of the button says so;

models\classes\*.pt) - the count keeps three pictures of every counted vehicle, and the model names the kind by them. What the detector called a car stays a car unless the model is 90 % sure it is a bus; a detector's car is never renamed a truck. What the detector called a truck or a bus is the model's to name. A motorcycle stays what the detector called it.

The choice takes effect on the next count. The pictures take about 50 MB for a half-hour recording and lie in the folder of the run.

The VEHICLES OF THE RUN card - the pictures of the vehicles of the chosen run:

sure of; a half-hour recording usually has some tens to a couple of hundred;

The buttons under a vehicle - CAR, TRUCK, BUS, NOT A VEHICLE - set its kind. A mark corrects the results of the run in RESULTS at once; the kind of the detector and the kind of the model stay beside it in the table of events (events.csv: detector_class, classifier_class, classifier_share, mark), the marks lie in review.csv of the run's folder. NOT A VEHICLE takes the vehicle out of the results: two vehicles in one box, not a vehicle of the three kinds.

How to mark: a route van - a minibus with windows along the whole side - is a bus, as in the sheets of the people who count by hand; a Gazelle without windows along its side, a van, a flatbed is a truck; a minivan, a UAZ van, an ambulance, a pickup is a car.

The marks are also the examples a model of kinds is taught on for your cameras. The model is taught by commands of the engine (most easily by an agent, see "Working with Claude and Codex") and comes as a new file in models\classes, in the MODEL OF KINDS card beside the earlier ones. There is no teaching button in the window.

Working with Claude and Codex

The program is made to be worked on together with an AI agent - Claude Code or Codex - the way its authors worked on it. The guide for the agent is Docs\AI_AGENT_GUIDE_EN.md (in Russian: AI_AGENT_GUIDE_RU.md): the commands of the engine, the file formats, the order of the work and what has already been measured.

How to start. Install the program (SETUP, INSTALL WHAT IS NEEDED), open its folder in Claude Code or Codex, and ask in your first message to read Docs\AI_AGENT_GUIDE_EN.md. Then speak plainly:

pictures" - the agent takes a frame from the middle of each recording, draws the lines and gates and shows them on the frame;

sheets" - the agent shows the pictures, and the dispute is settled by the eye;

Teaching the kinds with an agent goes so:

  1. the agent cuts pictures of every vehicle of a part of a recording (the command

harvest) or takes them from a run counted with a model of kinds;

  1. lays them on sheets of 48 (sheets) - first everything the detector called a bus or a

truck, then a sample of the cars;

  1. looks at the sheets and gives every vehicle the letter of its kind (labels) - tell it

how your sheets count route vans and small trucks, and look at a couple of its sheets;

  1. teaches the model (teach) - half an hour on a laptop processor, minutes on an NVIDIA

card;

  1. checks it on vehicles it has not seen (check-classes) and tells by how many percent the

count of each kind is off;

  1. you choose the model in the TRAINING section, and the next count goes with it.

The main thing we learned: what decides is not the length of the teaching but pictures from cameras of the same kind and the right boundary between the kinds. Two hundred labelled vehicles of your own camera do more than thousands of others. In detail: the guide for the agent, "Teaching the kinds for the user's cameras".

About the recordings. The agent works on your machine, and the recordings themselves go nowhere. But what the agent looks at - a frame to place the lines by, sheets of pictures to label - goes to the service it runs on (Anthropic for Claude, OpenAI for Codex). If the recordings must not be shown to others, label them yourself: by the buttons of the TRAINING section or by letters in the files beside the sheets - the agent then needs only the commands, not the pictures.

The agent does not start the count of the queue itself: that is the COUNT button.

SETTINGS

How the program itself works (the button at the bottom left, between SETUP and ABOUT).

The SPEED OF THE COUNT card - these settings do not change the counts, only the time:

an NVIDIA card, four by default. When one is through, the next takes its place. A machine without an NVIDIA card counts recordings one at a time.

SETTINGS has a field for every kind of data: the recordings, the work folder, the reports, the project file, the training data. Recordings and reports can be had again - the recordings copied anew, a report written once more; what the program has learned (the model of vehicle kinds) lies in the program itself.

The RECORDINGS card - the folder the recordings lie in. The program only reads them. The choice of files in the RECORDINGS section opens in this folder. When the recordings were moved to another disk or copied anew, choose the new folder here: the recordings of the list that are not where they were are found in it and in its subfolders by the name and the fingerprint of the file, and their lines and results stay with them. The program does the same at every start.

The REPORTS card - the folder the Word and Excel reports are written into; the report buttons of the RESULTS section open the choice of a folder at this place.

The WORK FOLDER card - where what the program writes about your recordings lies: the list of recordings, the lines and gates, the results of the counts, the sheets of manual counts to compare with, the journal. IN THE PROGRAM'S FOLDER (the default) - all of it in the folder of the program itself. IN THE USER'S FOLDER - in the folder you choose, and the folder of the program holds the program and its settings alone: it can be copied to another machine, cleaned and handed over without carrying the lists, the lines and the results along. The layout of a work folder is the one of the program: config\recordings.json, config\cameras\, output\, reference\, logs\. Choosing a folder moves nothing: to take the former work along, close the program and move these folders and the list file into the new work folder. The folder is changed without a restart; it cannot be changed while a count runs.

The PROJECT FILE card - where the second copy of the lines of the recordings is kept (see "The project file").

The TRAINING DATA card - where the pictures of vehicles, the sheets, the labels and the sets for teaching a model of kinds lie: BESIDE THE RECORDINGS (a folder classes beside the videos - the default, the data travel with the recordings) or IN THE USER'S FOLDER. The program never erases them, and they do not go into a publication of the program.

Keys

KeysWhat they do
Ctrl+1 … Ctrl+8the sections in order
Ctrl+Jthe journal
F1this guide
Escfrom SETUP, SETTINGS and ABOUT - back; in CAMERA - back to the pointer
SpaceCAMERA: play or stop the video
← →CAMERA: a frame back and forward
Page Up, Page DownCAMERA: the previous and the next recording
DeleteCAMERA: remove the chosen line or zone

What accuracy to expect

or two percent (on the check recording: +0.8 % and -0.1 % on the two lines by the camera).

and a larger model help; the smallest ramps of a low-resolution recording are beyond what the program sees.

by the detector alone roughly (on the check recording, at one line: buses -53 %, trucks +39 %); with a model of kinds taught on a camera of the same type, within a few percent (there: +6 % and +4 %; see TRAINING). Trucks are not split by the number of axles.

runs made on the same one.

Where things are

FolderWhat is in it
App\, Start.exethe window of the program
runtime\, models\, Tools\Python with its libraries, model weights, FFmpeg - installed by the SETUP section
models\classes\your own models of kinds for the TRAINING section
system_core\kinds\the model of kinds that comes with the program
classes\ beside the videosthe training data: pictures, sheets, labels, sets and copies of the models (or the folder chosen in SETTINGS)
config\settings.jsonthe settings of the program - always in its folder
the work folderthe list of recordings, the lines, the results, the manual counts and the journal - the four rows below. It is the folder of the program until another one is chosen in SETTINGS
config\recordings.json, config\cameras\the list of recordings and the placements of lines, a file per recording
output\<recording>\<date-time>_<model>\a run: events.csv, summary.json, the lines it was counted with; with a model of kinds - crops\ (pictures of the vehicles) and review.csv (the marks)
reference\manual counts to check against
audion-traffic-counter.json in the folder of the videosthe project file: a second copy of the lines, beside the recordings
logs\the journal, a file per day

What the program does on the network and on the machine

It collects nothing and sends nothing. It goes to the network only during installation and at the first count with a new model - to download Python (python.org), the libraries (PyPI, pytorch.org), the model weights (GitHub), FFmpeg (gyan.dev, GitHub) and 7-Zip to unpack it (7-zip.org).

It installs nothing into the system: no services, no scheduled tasks, no registry entries. To remove the program, delete its folder.

If something goes wrong

What you seeWhat to do
"The counting engine is not installed"the SETUP section, INSTALL WHAT IS NEEDED
"FFmpeg was not found", no video in CAMERAthe SETUP section, the FFMPEG button
SETUP asks to update the NVIDIA driverupdate the driver and press CHECK AGAIN
a recording says "no lines", the queue says "will be skipped"draw the lines in CAMERA
a line counts nothingits arrow points the wrong way: turn it with the arrow button in the row of the line
a far line counts far fewer than there aredraw a zone with enlargement, take a larger model
"the edits of its lines are not saved … - the recording is not counted"the recording has a line without a movement name, or not a single line is left: fix it in CAMERA and count it again
"the count failed" on one recordingthe file cannot be read as a video, breaks off before its end, or its frame size differs from that of its lines; details are in the journal
"the engine was silent … - stopped"the engine hung; the queue went on. Count this recording again; if it repeats, choose another way to count in COUNT
the count is slowit runs on DirectML or on the processor: look at the "Count on" row in COUNT
All projects