showcues

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   

Latest Version is 1.0.43

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.

Supported

Install

• Use pip to install

python3 -mpip install showcues 
# and / or 
pypy3 -mpip install showcues

Upgrade

• Use pip to upgrade

python3 -mpip install --upgrade showcues 
# and / or 
pypy3 -mpip install  --upgrade showcues

Run

• 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,0x46

expand_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
  

CUE-OUT

• A CUE-OUT is 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
                                                             

CUE-IN

• A CUE-IN is 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

AUTO CUE-IN

• An AUTO CUE-IN such as with a Break Auto Return, includes the word AUTO

2023-06-19T03:03:47 AUTO #EXT-X-CUE-IN  Diff: 5.539 
Media: index_375_00039.ts

SCTE-35

• A SCTE-35 indicates SCTE-35 data in the segments. A SCTE-35 label 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=

Invalid

• Invalid indicates 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

• Live clock at the bottom of the page.
  • Wall Clock Time
  • PTS

 2023-08-23T08:58:21.07Z PTS:38247.104111

Sidecar

• A Sidecar file, sidecar.txt is 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

Supported

• 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