Your barcode pipeline is wired to the camera, and that is exactly what makes it hard to test. Mock the code string and you skip the decoder entirely; point a device at a printed label and the test now depends on lighting, focus and a steady hand. There is a third way: keep the real decode call, drop the camera, and hand the decoder a frame you built from a saved image. The decode input is just an 8-bit grayscale byte buffer, so a PNG captured from a real run converts to that buffer in two commands. This guide shows how to capture reference frames, cut the luma plane out of them, wrap the bytes behind the frame interface your decoder expects, and run the full capture-to-result path in a unit or instrumented test with no camera attached.
What a barcode decoder actually reads
A monochrome barcode decoder never talks to a camera. Its read() method consumes three things: a width in pixels, a height in pixels, and one uncompressed 8-bit buffer of width × height bytes — the luma plane. Planar YUV formats, the layout camera pipelines have used since the days of analog capture hardware, store exactly that: one byte per luma pixel in the first plane, with the chroma planes following behind it in the file.
An Android pipeline delivers the same layout inside its image proxy object: plane 0 is the luma channel the decode wrapper actually reads, while rotation, crop and timestamps are metadata for your code, not for the decoder. Once you see read() as a pure function from bytes to code strings, the camera becomes a replaceable part. Any object that returns the right width, height and plane 0 buffer decodes exactly like a live frame. That is the whole method: implement the frame interface once, feed it stored bytes, and the real decoder runs.
The same logic holds on the factory floor. Where your decode code runs on-device, an X86-platform smart camera such as LS-SMC-0017 (8.8 MP, C-mount) gives it a home on the camera itself, and the replay tests travel with it unchanged.
- Interface
- USB 2.0
- Resolution
- 6-10 MP
- Sensor format
- 1"
- Shutter
- Global
If you are still weighing whether to own the decode call at all, the build-or-buy comparison for software barcode decoding marks where a self-contained reader ends and your own code begins.
Capture the frames you will replay
Save frames from the real station once, with the real optics, and cover the failure modes you will meet in production: a clean code at working distance, a small code in a large frame, a tilted code, a low-contrast or damaged code, and one empty scene with no code at all. Store each frame at the exact pixel size the pipeline delivers, so the bytes you replay match what the camera would have handed over. Capture with the camera the station will actually run — the smart cameras category holds the mono on-device models, for example the MV-SC5060XM-08M-WBN, a 6 MP mono smart camera whose frames are already single-channel gray on the way to the decoder.
- Interface
- GigE
- Resolution
- 6-10 MP
- Sensor format
- 1/2.4"
- Shutter
- Rolling
If the camera is 10- or 12-bit capable, scale to 8-bit before saving; the pitfalls section covers what happens when you skip that. Frames on disk stop belonging to one device — any tool on any machine can read them, the same pattern as wrist camera images that feed external processing tools. And when you archive frames for later suites, keep them in a form that survives the round-trip: the guide on saving 16-bit grayscale camera images reliably compares the working storage formats.
Injecting fake frames one layer lower, at the driver level, is also possible — a virtual USB camera that feeds test images with no hardware does exactly that. This method sits one level deeper, handing bytes straight to the decode call, so it also works on devices where you cannot install a driver.
Turn a PNG into a luma plane
Two commands take a saved frame to a decoder-ready buffer: convert the PNG to raw planar YUV, then keep only the first width × height bytes. Raw YUV output stores the luma plane first and the chroma planes behind it — the layout described above — so the file's tail is exactly the part the decoder never reads. The conversion and the cut:
convert frame-1920x1080-clean.png -colorspace YUV frame.yuv
dd if=frame.yuv of=luma bs=2073600 count=1
The block size is this frame's width × height in bytes; the worked example below shows where 2073600 comes from. count=1 takes one such block and drops the chroma.
If your build cannot run external tools, convert in code instead: load the PNG, compute each pixel's gray value with the standard BT.601 luma weights, Y = 0.299 R + 0.587 G + 0.114 B, and store the results in a byte array. For gray or near-gray content the result lands within a few gray levels of the camera's own converter, far from anything that changes a decode.
Worked example: 1920 × 1080 PNG to a 2,073,600-byte luma plane
The inputs, and where each comes from:
- Frame size 1920 × 1080 px — read off the saved PNG; substitute your own width and height.
- One 8-bit byte per luma pixel — the planar YUV layout described above.
- Decoder input of plane 0 only — what a monochrome barcode reader consumes through its wrapper.
The rule in words: the luma plane carries one byte per pixel, so its size is width × height bytes. A YUV420 file also carries two chroma planes at half resolution, so the whole file is 1.5 times the luma size.
The arithmetic:
- Luma: 1920 × 1080 = 2,073,600 bytes = 2025 KiB (2,073,600 ÷ 1024).
- Full YUV file: 1.5 × 2,073,600 = 3,110,400 bytes.
- Chroma tail that dd drops: 3,110,400 − 2,073,600 = 1,036,800 bytes — two planes of 960 × 540 = 518,400 bytes each.
- dd block size for one clean cut: bs = 2,073,600, count = 1.
The result: wc -c luma prints 2073600, and the luma plane is two thirds of the YUV file (2,073,600 ÷ 3,110,400).
The decisions: a byte count of 2073600 means the buffer is ready to wrap. A count of 3110400 means dd copied the whole file and the decoder will read chroma as gray noise — fix the block size. A smaller count means a truncated frame with its last rows missing. If the size is right and the decode still fails on a frame your viewer app reads, the cause is stride or pixel format, not size. Run the empty scene through the same path too: the decoder must return no result there, which sets your false-read budget at zero.
Wrap the bytes behind the frame interface
Build the test double around the four things a decode wrapper reads from a frame: width, height, pixel format, and planes. On Android, the pipeline's ImageProxy is an interface, so you implement it yourself: wrap your ByteArray in a ByteBuffer, put that behind a PlaneProxy, and return it for plane 0, declaring a row stride equal to the width and a pixel stride of 1 byte. Width and height come from the file name or the PNG header. Everything else the interface demands can return neutral values, because a monochrome reader ignores it.
This is the same luma-first layout your app already handles when it scans barcodes from its own Android preview loop; the double simply delivers it without a camera in the loop. Keep the buffer alive for as long as the read() call runs: the decoder reads the bytes you hand it, so a buffer collected early decodes as garbage. The guide on decoding from image buffers without losing pixels walks through that failure in detail.
Run it in the test
The replay harness is a short numbered procedure:
- Load the luma file into a byte array of exactly width × height bytes, with width and height taken from the file name.
- Wrap the array in a byte buffer and present it through your frame implementation for plane 0.
- Call the same read() method the production pipeline calls, with your frame object as the argument.
- Assert the decoded text equals the value printed on the captured label — declare it as a constant, for example TEST-000123, next to the frame file.
- Assert the empty-scene frame returns no result at all; one false read means the decoder's sensitivity is set for noise.
- In the instrumented UI test, swap the app's frame source for the replay source: production builds take the camera, the test build takes the files, and the screen exercises the real capture-to-result flow.
A type error — the decoder refusing your input rather than returning a failed read — means the declared pixel format does not match the bytes; the input-type error checklist for barcode decoders sorts those cases quickly. A green run here proves your decode path: decoder configuration, result parsing, and the app's response to a code. It does not prove the lens.
What replay testing proves and what it does not
Proved: the decoder and its settings, your parsing of the result string, and whatever the app does next with the code — write to a buffer, route a part, show a pass screen. Not proved: focus, exposure, glare and motion blur, which happen in the optics and the light and are frozen into a saved frame rather than caught by the test. Keep one hardware smoke test on the bench — camera, printed label, real trigger — and run it when the optics or lighting change, not on every commit.
Two frame-level traps bite industrial cameras. A 10-bit PNG looks black in normal viewers and decodes black for the same reason — scale to 8-bit first, as explained in why 10-bit PNG images look black. A 12-bit frame keeps its extra precision only if the save path preserves it; the guide on saving 12-bit frames as 16-bit PNG or TIFF shows the formats that work. And a replayed frame with motion blur baked in fails every run — recapture with more light or a shorter exposure instead of tuning the decoder around it.
None of this applies to self-contained fixed code readers, which decode inside the reader and hand out a result rather than a frame. Replay testing is for decode code you own; the reader itself you test at the station.
Checklist before you trust a green run
- Buffer length equals width × height, asserted in the test code — a wrong length reads chroma as gray or truncates the last rows.
- Plane 0 declared with a row stride equal to the width and a pixel stride of 1 byte — anything else skews the image diagonally.
- The empty-scene frame returns no read — the decoder is not tuned into noise.
- A deliberately damaged frame returns no read rather than a wrong string — a mis-read costs more than a failed read.
- Every frame stored at the pipeline's native size, uncropped and unscaled — resizing hides the very failures you replayed it for.
- Every production failure added as a new replay frame with its expected string — that regression then dies in the suite, not on the line.
Run the suite on every decoder or parsing change; it finishes in seconds and needs nobody at the bench. The rest of the decode-side material — trigger modes, serial framing, buffer handling — sits on the code-reading topic page. When the replay tests pass and what is still missing is the capture hardware, the camera finder filters fixed code readers and smart cameras by resolution and interface, and the configurator starts you at the camera step:
The configurator matches a camera, lens, light, light controller and cables to each other, step by step, and lists only parts that fit what you already picked.
Questions
Do I need the chroma planes for a monochrome decoder?
No. A monochrome barcode reader reads plane 0 only, so the 1,036,800 chroma bytes that follow the luma plane in a 1920 × 1080 YUV420 frame are dead weight in the test file. Keep them out by cutting the first width × height bytes. The exception is a code that genuinely encodes data in color; then decode from a three-channel image and check that your decoder's color path is enabled.
How many pixels per module does a replayed image need?
Use the same rule of thumb as live capture: about 3 pixels per module for reliable 1D and DataMatrix reads, with marginal codes starting to fail near 2 pixels per module and bars merging below that. Check it on your saved frame: a 12-module DataMatrix symbol at 3 pixels per module needs 36 pixels per side, easy inside any frame you would replay.
Can I skip the PNG and replay the camera's own bytes?
Yes, and it is the tighter test. While the camera pipeline is live, write plane 0's buffer straight to a file and put the width and height into the file name, for example luma-1920x1080-line3.raw. The test then loads exactly the bytes the camera delivered, with no conversion step to drift. Keep one PNG set as well, so you can still view the frames in an image editor.
Why does my replayed frame decode in the phone app but fail in the test?
Almost always a format mismatch rather than a bad image: the decoder was given RGB pixels, a row stride different from the width, or a 10-bit buffer instead of 8-bit. A monochrome reader expects one 8-bit plane, tightly packed, width × height bytes. Print the buffer length and the declared stride before blaming the decode itself; they disagree with the expectation more often than the decoder is wrong.
How many test frames should I keep?
Five to ten, chosen to spread the failure modes: one clean code, one small in the frame, one tilted, one low-contrast or damaged, and one empty scene. Add a frame every time production returns a code that read wrong, so that regression can never come back silently. Past about twenty frames the set slows the suite without catching much more.

