A Super Cool HLS SCTE-35 Debugging Tool powered by threefive
showcues development was financed by the fine folks at tunein.com
2023-11-13T01:17:39.83Z SCTE-35
Stream PTS: 49321.142044
PreRoll: 9.400011
Splice Point: 49330.542055
Type: Splice Insert
Media: index_2_3332800.ts Debugging SCTE-35 Cues in live HLS streams can be a traumatic experience.
SCTE-35 Cues can be embedded in the stream or inserted with HLS tags into the manifest.
To make it a little more complicated,
there are at least four different SCTE-35 HLS tags options currently in use.
showcues is designed to parse all SCTE-35 data currently used in HLS.
- Use pip to install
python3 -mpip install showcues
# and / or
pypy3 -mpip install showcues- Use pip to upgrade
python3 -mpip install --upgrade showcues
# and / or
pypy3 -mpip install --upgrade showcues- showcues takes a master m3u8 OR variant m3u8 (new with v.1.0.5) as input.
- showcues displays where the SCTE-35 cues are based on the SCTE-35 data.
- showcues follows the rules we will be applying to SCTE-35 in HLS.
- Incorrect HLS tags are reported as invalid.
- Missing CUE-INs from break auto-returns are automatically added.
showcues https://nmxlive.akamaized.net/hls/live/529965/Live_1/index.m3u8[ Help ]
To display help:
showcues help
[ SCTE-35 Parsing Profiles]
Parsing profiles allows you to adjust how showcues parses SCTE-35.
running the command:
`showcues profile`
will generate a default profile and write a file named sc.profile in the current working directory.
a@fu:~$ cat sc.profile
expand_cues = False
parse_segments = False
parse_manifests = True
hls_tags = #EXT-OATCLS-SCTE35,#EXT-X-CUE-OUT-CONT,
#EXT-X-DATERANGE,#EXT-X-SCTE35,#EXT-X-CUE-IN,#EXT-X-CUE-OUT
command_types = 0x6,0x5
descriptor_tags = 0x2
starts = 0x22,0x30,0x32,0x34,0x36,0x44,0x46expand_cues: set to True to show cues fully expanded as JSON
parse_segments: set to true to enable parsing SCTE-35 from MPEGTS.
parse_manifests: set to true to parse the m3u8 file for SCTE-35 HLS Tags.
hls_tags: set which SCTE-35 HLS Tags to parse.
command_types: set which Splice Commands to parse.
descriptor_tags: set which Splice Descriptor Tags to parse.
starts: set which Segmentation Type IDs to use to start breaks.
Edit the file as needed and then run showcues.
[ Profile Formatting Rules ]
-
Values do not need to be quoted.
-
Multiple values are separated by a commas.
-
No partial line comments. Comments must be on a separate lines.
-
Comments can be started with a # or //
-
Integers can be base 10 or base 16
[ Output Files ]
-
Created in the current working directory
-
Clobbered on start of showc ues
-
Profile rules applied to the output:
- sc.m3u8 - live playable rewrite of the m3u8
- sc.sidecar - list of ( pts, HLS SCTE-35 tag ) pairs
-
Profile rules not applied to the output: * sc.dump - all of the HLS SCTE-35 tags read. * sc.flat - every time an m3u8 is reloaded, it's contents are appended to sc.flat.
[ Cool Features ]
-
showcues can resume when started in the middle of an ad break.
2023-10-13T05:59:50.24Z Resuming Ad Break 2023-10-13T05:59:50.34Z Setting Break Timer to 17.733 2023-10-13T05:59:50.44Z Setting Break Duration to 60.067 -
mpegts streams are listed on start ( like ffprobe )
Program: 1 Service: Provider: Pid: 480 Pcr Pid: 481 Streams: Pid: 481[0x1e1] Type: 0x1b AVC Video Pid: 482[0x1e2] Type: 0xf AAC Audio Pid: 483[0x1e3] Type: 0x86 SCTE35 Data Pid: 484[0x1e4] Type: 252 Unknown Pid: 485[0x1e5] Type: 0x15 ID3 Timed Meta Data
[ Example Usage ]
-
Show this help:
showcues help -
Generate a new sc.profile
showcues profile -
parse an m3u8
showcues https://example.com/out/v1/547e1b8d09444666ac810f6f8c78ca82/index.m3u8
- A
CUE-OUTis shown with:- Wall Clock Time
- PTS
- Duration
- The Segment URI
2023-08-29T10:30:19.39Z OUT
PTS: 72829.7572
Media: seg81.ts
Duration: 119.986533
- A
CUE-INis shown with: - Wall Clock Time
- PTS
- The Segment URI
- The Diff of when the CUE-IN should be and when it actually occurs.
2023-08-29T10:30:19.43Z IN
PTS: 72947.8752
Media: seg140.ts
Diff: 0.064734
- An
AUTO CUE-INsuch as with a Break Auto Return, includes the wordAUTO
2023-06-19T03:03:47 AUTO #EXT-X-CUE-IN Diff: 5.539
Media: index_375_00039.ts- A
SCTE-35indicates SCTE-35 data in the segments. ASCTE-35label is shown with:- Wall Clock Time
- PTS
- The Segment URI
- The Base64 encoded SCTE-35 Cue
2023-08-29T10:30:19.43Z SCTE-35
PTS: 72949.8772
Media: seg141.ts
Cue: /DAsAAAAAyiYAP/wCgUAAAABf1+ZmQEBABECD0NVRUkAAAAAf4ABADUAAC2XQZU=
Invalidindicates an invalid HLS CUE Tag, such as two consecutive CUE-IN tags. An Invalid label includes:- Wall Clock Time
- PTS
- The Segment URI
- The invalid HLS tag.
2023-08-29T10:30:19.43Z Invalid
PTS: 72955.8832
Media: seg144.ts
Tag: #EXT-X-CUE-IN
- Live clock at the bottom of the page.
- Wall Clock Time
- PTS
2023-08-23T08:58:21.07Z PTS:38247.104111- A Sidecar file,
sidecar.txtis generated containing a list of ( pts,cue ) pairs.
a@debian:~/tunein/showcues$ tail -f sidecar.txt
58363.607489,/DBFAAH/7S+YAP/wFAUAAAABf+//ORY3wv4AzgQwmZkBAQAgAh5DVUVJAAAAAH/AAADN/mABCDEwMTAwMDAwNAAAAADgrVWi
59305.014622,/DBFAAH/7S+YAP/wFAUAAAABf+//PiMLNP4ApMbEmZkBAQAgAh5DVUVJAAAAAH/AAACky4ABCDEwMTAwMDAwNAAAAAClR6us
59595.771756,/DBFAAH/7S+YAP/wFAUAAAABf+//P7JWgv4Azey6mZkBAQAgAh5DVUVJAAAAAH/AAADN/mABCDEwMTAwMDAwNAAAAAC+xYYV-
M3U8 formats
- master ( When a master.m3u8 used, showcues parses the first rendition it finds )
- rendition
-
Segment types
- AAC
- AC3
- MPEGTS
-
Protocols
- File
- Http(s)
- UDP
- Multicast
-
Encryption
- AES-128 (segments are automatically decrypted)
-
SCTE-35
- All 2022-b Splice Commands
- All 2022-b Splice Descriptors
- All 2022-b UPIDS
-
SCTE-35 HLS tags
- #EXT-X-CUE-OUT
- #EXT-CUE-OUT-CONT
- #EXT-X-CUE-IN
- #EXT-X-DATERANGE
- #EXT-X-OATCLS
- #EXT-X-SCTE35
- #EXT-X-SPLICEPOINT-SCTE35
- #EXT-X-SCTE35