Add userbit support for LTC/SMPTE

[robertmcrostie]

Amazing bit of open source software.

Would it be possible to add UserBits to the LTC/STMPE in/out? I know not many people use or know if userbits but occasionally I have use them for controlling equipemnent while still using the same timecode range. Thanks.

[fiverecords]

Thanks, glad you're finding it useful!

Yes, this is doable. The LTC frame already carries 32 bits of user bits (eight 4-bit groups), and STC's encoder and decoder already lay the frame out correctly, so adding read/write for those bits is a fairly contained change.

To make sure I build it the way you need it: on the output side, are you looking to set a fixed value (e.g. an 8-digit hex field you enter once), or do you need the user bits to change over time? And on the input side, do you just want to see the incoming user bits displayed/logged, or feed them somewhere? Also, is there a particular format your equipment expects in those bits (raw hex, date, reel number...), or is it a value you define yourself on both ends?

Once I know that, I can put together a build for you to try.

[robertmcrostie]

Thanks, it is nice to have userbits working.

This is how I have or seen it used in the past:

1. We would set the userbits to be the date of when the laser show was created. The timecode track would be stripped with the same date in userbots so when the audio and timecode would play on a sony mini disk that had 4 tracks, the show would only run when the correct timecode and userbit were being sent. This was a bit of a safety so if there was a timecode test or similar with other timecode it would not trigger the show.  
2. I have used this to trigger different laser shows for an information centre using the same timecode but with different userbits that would play different laser shows that were loaded into the laser controller. It allowed us to use the same timecode with just change the userbits to trigger the different shows. This avoids lots of things like timecode free rolling and triggering another show etc etc. 

Functions that would be good to have:

1. Display of the userbits from the incoming timecode converted to a decimal number. Normally we would use say YYYYMMDD (I think that is correct from memory as it was a while ago).
2. Pass through option so what is received is transmitted out. This would only be relevant to LTC/SMTPE as not sure how the other types of timecode handle userbits. 
3. In generation mode allow the user to set the userbits.
4. Yes the userbits would be just a value that the user defines.
5. When you are using the system clock to generate timecode have the option of sending userbits as the current system date or setting it to another number. 
6. The other methods of timecode input and output I would think it is nice to have userbits set either from the original or changed to a value we have in the software.

I have not used userbits for a while but it does make the LTC/STMPE complete. Hopefully that all makes sense but if you have another way to do this I am happy either way.

[mungewell]

Using the beta @fiverecords sent out yesterday, it looks like the UserBits are sent in reverse order... or maybe I'm wrong.

Additionally UserBits can also be in different formats:

• 8x hex digits (as used)
• Name = 4x ASCII characters
• Date = format which encodes year/month/day and timezone
• Page/Line = it's complicated... for scripty I guess

EDIT:

My FR-AV2 display 'userbits' in the 'Timecode/Info' page, but these never seem to change and there's no way to edit them.

My Ultra-Sync has a menu to edit the userbits (as 4x 8bit hex), but then sends them as 8x hex digits (not ASCII as I had expected). The order matches on my device.

[mungewell]

Here's the code/order I use for the default name = 'PICO' on my board:
https://github.com/mungewell/pico-timecode/blob/main/pico_timecode.py#L478

Although I note that the functions for digits seem to include a reversal, so perhaps I coded up to match the (incorrect?) Ultra-Sync...
https://github.com/mungewell/pico-timecode/blob/main/pico_timecode.py#L810

Happy to change my code if that's the better option, or matches more devices.

[mungewell]

I just remembered that SMPTE org decided recently to open all their specs for free download... this is the canonical reference.
https://pub.smpte.org/doc/12/

As far as I can tell there is no 'sequence rule' for the use of user-bits as 'digits' (ie 8x 4bit hex), but 'name' (ie 4x 8bit ASCII) uses ub7&8 for the first character. This seems backwards, but them's the rules. ;-)

EDIT:
The follow-on spec (ST309) describes the "Date" format (including timezone), and DOES specify which user-bits/binary-groups to use for each of "DD" "MM" and "YY". The time-zone is encoded in ub7*8.

EDIT2:
I found a 3rd piece to the puzzle, although not a spec....
https://goprotelemetryextractor.com/tools-for-ltc-audio

The User Bits must contain the current date as either yyyymmdd or ddmmyy00.

They also talk about using UTC (not that I'm suggesting it for STC). Given the encoding for UTC (in ST309) is '0x00', their suggestions would align with that.

Summary: I think that my Ultra-Sync is wrong, and think I will change my code to match what STC currently does.

PS. If you chose to implement 'name' (4x ASCII) the default could be 'STC1', 'STC2', etc based on which engine was outputting LTC.

[fiverecords]

@robertmcrostie User bits are in the release that just went out. On the LTC output there's a
source selector with four options: a fixed hex value you type, passthrough of
whatever arrives on the LTC input, the current date, or a four-character
name. On the input side the recovered value is displayed alongside the
timecode.

Two things aimed at your use cases specifically. The passthrough mode holds
the last received value if the incoming signal drops out rather than falling
back to zeros, so equipment gating on user bits won't lose them during a
glitch. And the input display shows the raw hex plus, when all eight digits
are 0-9, the decimal reading and a date interpretation if the digits look
like one — so an incoming 20260724 shows as 20260724 (2026-07-24).

The date mode writes YYYYMMDD, which is what you described. Worth knowing
that this is not the SMPTE ST 309 date format, which uses a different layout
with a time zone code. STC leaves the binary group flags cleared, which marks
the data as user-defined, so nothing should misread it as a standards-based
date. A proper ST 309 mode would be a separate option.

Give it a try with your equipment when you get a chance and let me know how
it behaves.

@mungewell Thanks for digging into the ordering, and for the spec extracts — they
settled it.

Your conclusion matches what STC does: most significant hex digit in binary
group 1, bits least-significant-first within each group. As you found, ST 12
imposes no sequence rule when the groups are used as plain hex digits, which
is why devices disagree. The GoPro convention you linked only works if the
year lands in the first groups, so that's a second data point for it.

Table 4 was the missing piece for the date format, and it's a good
illustration of why I didn't want to guess: units come before tens in
ascending group order, so 3 September 2026 encodes as groups 3 0 9 0 6 2.
And §8.4.2 confirmed your ASCII ordering exactly — first character in groups
7 and 8, least significant nibble in group 7. That's implemented in this
release as a NAME mode: four characters, defaulting to STC1, STC2 and so
on per engine. STC1 packs to 0x13344535, with the flags set to declare an
eight-bit character set.

Still missing for a real ST 309 date mode: the time zone code table for
groups 7 and 8. I checked and ST 309 isn't in SMPTE's free library — it
carries ST 12-1 and the 2059 family but not 309. If you can post that table
I'll implement the full date mode with the correct flags. Until then the
date mode stays free-form YYYYMMDD with the flags cleared, which claims
nothing.

One other thing came out of reading 12M-1 for this: STC had a bug where the
polarity-correction bit was being written at both possible positions instead
of the frame-rate-correct one, so at 30 and 24 fps roughly half of all
outgoing frames were accidentally declaring ST 309 date data through the
flags. Fixed in this release. Your prompting is what led me to that table.

[mungewell]

ST309 is on the web too...
https://pub.smpte.org/doc/st309/

[fiverecords]

@mungewell You’re right, and thank you — it is there. The document page only lists the two editions; the PDF is inside the 2012 publication bundle, which is what I’d missed.
With the standard in hand the date mode is now the real thing: YYMMDD in groups 1–6 per Table 4, the zone code in groups 7–8 per Tables 1 and 2 with the DST flag, and BGF2 set per Table 3 (unspecified clock reference). Zone and DST come from the system clock and are re-read every second so midnight and DST changes are followed. I’m not emitting the MJD form: it requires the time address itself to be UTC, and STC’s clock mode runs on local time.
The reader side decodes the flags too, so an incoming ST 309 date (either form) or a four-character label is shown as such instead of as hex. Your 0x13344535 reads back as “STC1”, which was a reassuring check of the character layout.
One detail from Table 2 worth knowing if you add it to Pico-Timecode: the codes read as decimal hours for whole-hour zones (00 = UTC, 01–12 = UTC−1 … −12, 13–25 = UTC+13 down to +1), half hours live in the A–F rows, 32 is Chatham, 38 is “user defined” and 39 “unknown” — which is what I send for offsets the table has no code for, such as +5:45.

[robertmcrostie]

@fiverecords No worries. Let me pull some gear out and do a little test rig and see what happens. I don't mind if we do change the date format to comply with the standard. Always like to keep with standards as there are alway good reasons that it was set that way. @mungewell great reading material information.

As soon as i have tested the software i will let you guys know. Thanks.

[mungewell]

@fiverecords I don't know how many LTC generators actually use the 'ST-309' format, for PicoTimecode I don't care about dates - other than to display them on OLED (if attached). For this I use "Y74-M02-D01+0000" and the timezone is referenced from a big table.
https://github.com/mungewell/pico-timecode/blob/main/pico_timecode.py#L452

I suspect that the 'correct' thing for STC to do is to check Windows (or Mac) local time-zone and fill as appropriate. There's also a 'precision' flag, I guess if your PC is sync'ed with NTP/GPS you could set that... but that's total overkill.

Technically the userbits can change over time, even switching between formats. But that's likely a recipe for confusing people's LTC readers. I'd stick with a static format if I were you.

On the order of bcd/hex digits; I found another application which outputs them in reverse order. But it also does padding if you set less than 8 digits (ie use -u 1234).
https://github.com/x42/ltc-tools

simon@portal:~/ltc-tools-github$ ./ltcgen --help
ltcgen - generate linear time code audio-file.
Usage: ltcgen [OPTION] <output-file>

Options:
 -b, --userbyte val         specify fixed user bits (0 <= val <= UINT32_MAX)
 -d, --date datestring      set date, format is either DDMMYY or MM/DD/YY
 -f, --fps fps              set frame-rate NUM[/DEN][ndf|df] default: 25/1ndf 
 -g, --volume float         set output level in dBFS default -18db
 -h, --help                 display this help and exit
 -l, --duration time        set duration of file to encode [[[HH:]MM:]SS:]FF.
 -m, --timezone tz          set timezone in minutes-west of UTC
 -r, --reverse              encode backwards from start-time
 -s, --samplerate sr        specify samplerate (default 48000)
 -t, --timecode time        specify start-time/timecode [[[HH:]MM:]SS:]FF
 -u, --userbits bcd         specify fixed BCD user bits as up to  8 BCD digits
                            CAUTION: This ignores any date/timezone settings!
 -V, --version              print version information and exit
 -z, --timezone tz          set timezone +HHMM

[fiverecords]

One thing I should have made explicit: the ST 309 date mode is implemented but not yet in a build you can download. The release you have still carries the free-form YYYYMMDD date with the flags clear, and the NAME mode. So @robertmcrostie, if your rig is ready before the next build is out, what it will see is the old date mode — I'll say here when a build with the ST 309 mode is available, and that's the one worth testing. If you can say which reader you'll use, I'll know what to expect from its display.

@mungewell Agreed on all four. Zone and DST come from the OS clock; the precision flag stays clear on purpose (a PC is not a precision clock in ST 309's sense, NTP or not); the format is static — only the values move, at midnight and at DST changes. On digit order: I looked at libltc, and it is the reverse of STC for free-form hex — ltc_encoder_set_user_bits puts the least significant nibble in group 1. ST 12 sets no order there, so that's just two conventions; STC's is documented. The useful part is that in date mode libltc uses the same ST 309 group layout and the same zone table, so ltcdump and STC will agree on the date; the only difference is that libltc doesn't set the DST flag.

[robertmcrostie]

@fiverecords I have a few TC boxed but the one that i know will read/write userbits is my Denecke Dcode SB-4 Syncbox Timecode Generator. I have some chinese ones but none of those read/write userbits that i know of. My Denecke will be my main unit. I think i have also some other TC software that will transmitt userbits as well. Will need to fire them up and see what each one does. Thanks.

[mungewell]

libltc doesn't set the DST flag.

OMG, that's another bundle of confusion... I remember when Bush changed the 'fall-back/spring-forward' dates in the US (and by association Canada), caused no end of confusion with meeting times. And now we have some Canadian premiers talking about messing with their provinces.

Decimal-UTC (or star-date) is the way to go! "XXXX.0' at midnight, up to 'XXXX.9999999' just before next midnight. Though not sure what to do with leap-seconds... ;-)

[mungewell]

Found another app ('Sidus TC Sync' by Aputure) which reports the User-Bits, this looks OK for STC but a bit odd for PicoTimecode!

EDIT:
I am an idiot for not updating my board - fixes order.... Aputure is an idiot because they don't display Hex (0xF gets display as 15, 0xE as 14, etc)!

EDIT2:
That aside, when set to BCD/HEX digits, and input in STC (and PicoTimecode) of '12345678' is show in reverse (as '87:65:43:21').