How can AI count the people in a video?
A queue is easy to understand and surprisingly hard to measure. Before AI, to know how many people walked past a certain point, someone had to stand there with a clicker and count by hand — one click per person, hour after hour.
This note uses a short Python program that does the counting for you. It reads a video, uses an AI model called YOLO to count every person who walks across a line drawn on the video. At the end it saves a second copy of the video with boxes and a running tally, and prints the total.
The video used here is a 33-second clip of people walking through a queue. The program reports
In count: 6: six people crossed the line from left to right.
queue-management-demo.mp4 is a demo video from Ultralytics in the
ultralytics/notebooks repository on GitHub:
https://github.com/ultralytics/notebooks/releases/tag/v0.0.0
- Direct download link: https://github.com/ultralytics/notebooks/releases/download/v0.0.0/queue-management-demo.mp4
What YOLO and ObjectCounter do
YOLO stands for You Only Look Once. It is an AI model that looks at a picture once and
lists what it sees — people, cars, dogs — with a box around each one.
Ultralytics, the company
that publishes YOLO, also ships a ready-made helper called ObjectCounter. The helper
draws the boxes, follows each box from frame to frame, and keeps two totals: one for objects
crossing the line in one direction, one for the other direction.
Step 1: load the model and open the video
from ultralytics.solutions import ObjectCounter
import cv2
model_path = "yolo26n.pt"
video_path = "queue-management-demo.mp4"
# Get video properties: width, height, FPS (frame/second)
cap = cv2.VideoCapture(video_path)
width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
fps = cap.get(cv2.CAP_PROP_FPS)
The first line brings in the counting helper, and the second brings in OpenCV, the library that
reads and writes video files. model_path names the AI model:
yolo26n.pt, where the n means nano, the smallest and fastest
size. The first run downloads it automatically, about 5 MB.
cv2.VideoCapture opens queue-management-demo.mp4, then the next three lines
read its width, height and speed (25 frames per second). The program needs those numbers for two
reasons: the counting line is described in pixels, and the saved video must have exactly the same
size and speed as the original.
Step 2: draw the counting line
region_points = [(width-400, 300), (width-400, height), (width-350, height), (width-350, 300)]
Four pairs of numbers describe the four corners of a thin strip: top-left, bottom-left,
bottom-right, top-right. Every point is measured from the top-left corner of the picture,
which is (0, 0), and the bottom-right corner is
(width, height): x grows to the
right and y grows downwards. Horizontally, the strip is 50 pixels
wide, running from x = width-400 to
x = width-350. Vertically, it
runs from y = 300 down to the bottom edge at
y = height (674).
The strip stands upright because the people move sideways across the picture, from left to right.
Direction matters: a person moving from left to right across the strip is counted as IN, and moving from right to left is counted as OUT. In this video everyone walks left to right, so all six crossings are IN.
Step 3: create the counter
# Initialize ObjectCounter
counter = ObjectCounter(
model=model_path,
region=region_points,
show=True,
show_labels = False,
show_conf = False,
show_in=True,
show_out=False
)
This one object does the work. model is the AI model, region is the
strip from Step 2, and show=True opens a window so you can watch the video being
processed as it happens.
show_labels = False hides the class name above each box, in this case the word
person, and show_conf = False hides the confidence score, a number like
0.85 that says how sure the model is. With both hidden you get plain boxes, which are much easier
to read in a crowded queue. show_in=True and show_out=False ask for only
the IN tally to be drawn on the video.
Step 4: save a labelled copy of the video
# Define the codec and create VideoWriter object to save the output video
fourcc = cv2.VideoWriter_fourcc(*'avc1') # H.264, plays on Mac
out = cv2.VideoWriter('result_queue.mp4', fourcc, fps, (width, height))
if not out.isOpened(): # avc1 not available (e.g. Windows), use mp4v instead
fourcc = cv2.VideoWriter_fourcc(*'mp4v')
out = cv2.VideoWriter('result_queue.mp4', fourcc, fps, (width, height))
VideoWriter is the opposite of VideoCapture: it writes a new video file.
The fourcc code names the compression format. avc1 is H.264, which plays
smoothly on a Mac. If that format is not available on your machine — often the case on
Windows — the program falls back to mp4v so it still produces a file.
The output is called result_queue.mp4, so the original video is never overwritten.
Step 5: go through the video frame by frame
while cap.isOpened():
ret, frame = cap.read()
if not ret:
break
results = counter(frame)
annotated_frame = results.plot_im
# Write the annotated frame to the output video
out.write(annotated_frame)
key = cv2.waitKey(1)
if key == ord('q') or key == ord('Q'):
break
A video is a long row of still pictures called frames. The loop pulls one frame at a time.
ret is true while there are frames left, and becomes false at the end, which ends
the loop. Each frame goes into counter(frame), which finds the people, updates the
totals, and returns a copy with the boxes and the number already drawn on it. That copy is
results.plot_im, and it is what gets written into the new video.
cv2.waitKey(1) waits one millisecond for a key press. Press q or
Q in the video window to stop early; otherwise the loop runs to the last frame.
Step 6: close everything and print the total
cap.release()
out.release()
cv2.destroyAllWindows()
print("In count:", results.in_count)
Releasing the reader and the writer hands the files back to the operating system, and
destroyAllWindows() closes the preview window. The last line prints the IN total.
For this video it prints:
In count: 6
While the program runs you also see, in the preview window, the strip, the boxes around each person, and the count going up as each person steps across.
The whole program
from ultralytics.solutions import ObjectCounter
import cv2
model_path = "yolo26n.pt"
video_path = "queue-management-demo.mp4"
# Get video properties: width, height, FPS (frame/second)
cap = cv2.VideoCapture(video_path)
width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
fps = cap.get(cv2.CAP_PROP_FPS)
region_points = [(width-400, 300), (width-400, height), (width-350, height), (width-350, 300)]
# Initialize ObjectCounter
counter = ObjectCounter(
model=model_path,
region=region_points,
show=True,
show_labels = False,
show_conf = False,
show_in=True,
show_out=False
)
# Define the codec and create VideoWriter object to save the output video
fourcc = cv2.VideoWriter_fourcc(*'avc1') # H.264, plays on Mac
out = cv2.VideoWriter('result_queue.mp4', fourcc, fps, (width, height))
if not out.isOpened(): # avc1 not available (e.g. Windows), use mp4v instead
fourcc = cv2.VideoWriter_fourcc(*'mp4v')
out = cv2.VideoWriter('result_queue.mp4', fourcc, fps, (width, height))
while cap.isOpened():
ret, frame = cap.read()
if not ret:
break
results = counter(frame)
annotated_frame = results.plot_im
# Write the annotated frame to the output video
out.write(annotated_frame)
key = cv2.waitKey(1)
if key == ord('q') or key == ord('Q'):
break
cap.release()
out.release()
cv2.destroyAllWindows()
print("In count:", results.in_count)
Running it on your own computer
Download the zip file and unzip it to
a folder. It holds yolo_queue.py, queue-management-demo.mp4 and
pyproject.toml. Open the folder in Visual Studio Code, then type these three lines
in the terminal, one at a time:
uv python pin 3.12.10
uv sync
uv run yolo_queue.py
The first run downloads the YOLO model (about 5 MB) and then processes the video. On a recent
laptop it takes about a minute. A video window opens; let it play, or press q to stop
early. When it finishes you get result_queue.mp4 in the same folder and the total in
the terminal.
If you have not set up uv yet, start with How to install Visual Studio Code? and then the uv note for Windows or Mac.
Limitations
- Crowded scenes are hard. When people walk shoulder to shoulder, boxes overlap and the tracker can lose an identity, so the total drifts from the truth.
- A crossing is a crossing, not a visitor. Someone who steps back and forth over the line is counted twice, once IN and once OUT. This counts movements, not unique people.
- The line has to be in the right place. Put it where people walk straight through, not where they stop, turn around, or stand. A line too close to the edge of the picture gives the tracker no time to recognise the person before they leave.
- Small or blurred people are missed. Anyone far from the camera, moving fast, or filmed at night may never be boxed at all.
- The camera should stay still. With a moving camera, people appear and vanish as the view shifts, and the identities jump.
- Check against a manual count on a short clip before scaling up. Run it on
a clip where you have counted by hand, and compare the two totals. A few people either way is
normal for a small model like
yolo26n; a bigger model is more accurate but slower.
Further reading
- Ultralytics object counting guide — the official walkthrough of the same helper, with more options.
- ObjectCounter reference — every parameter, including
classesandregion. - The queue-management demo video — the original clip used in this note.
- YOLO26 model page — the model family and the meaning of the
n,s,mandlsizes. - How to get live video from your webcam? — the same frame-by-frame idea, reading a camera instead of a file.
- How does AI find the key points on your face? — another way of using a model to read a video frame.