threefive 2.2.91

threefive, Pythonic SCTE-35.

threefive

• threefive is a SCTE-35 Decoder / Parser library in Python3
• threefive references the 2020 SCTE-35 Specification.
• threefive decodes SCTE-35 from MPEG-TS video files and streams.
• threefive decodes SCTE-35 from Base64, Hex, and Binary encoded strings.
• threefive decodes SCTE-35 from ffmpeg Data: bin_data ([6][0][0][0] / 0x0006) streams.
• threefive is now testing a Golang version too..

---

• Versions and Releases

• Install threefive

• Quick Start

• Easy threefive

  • Parsing SCTE-35 Cues from Mpeg-TS Streams
  • Parsing SCTE-35 Cues from Mpeg-TS Streams over HTTPS
  • Parsing SCTE-35 Cue strings encoded in Base64, or Hex
  • Parsing SCTE-35 Cues directly from a file encoded in Base64, Binary, or Hex

• Advanced threefive

  • Cue Class
  • Stream Class

• Examples

  • DTMF Descriptor
  • Parsing HLS Manifests with threefive
  • SCTE-35 from a Multicast Stream
  • SCTE-35 from MPEG-TS video over HTTPS
  • Show SCTE-35 preroll
  • All Examples

• threefive Spotted in The Wild

• ffmpeg and SCTE35 and Stream Type and threefive

---

Versions and Releases

---

• Odd numbered versions are releases.
• Even numbered versions are testing builds between versions

a@fumatica:~/threefive$ pypy3

Python 3.6.12 (7.3.3+dfsg-3, Feb 25 2021, 22:28:03)
[PyPy 7.3.3 with GCC 10.2.1 20210110] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>> from threefive import version
>>>> version()
'2.2.82'

Install

---

• Requires python 3.6+ or pypy3

  • threefive runs 3x Faster on pypy3

• To install for the system, Install as root.

• install from pip (recommended)

$ pip3 install threefive

# for pypy3
$ pypy3 -mpip install threefive

#If you don't have pip installed, try this.
$ pypy3 -mensurepip install pip 

---

OR

• install from git

$ git clone https://github.com/futzu/threefive.git

$ cd threefive
$ make install

# for pypy3 
$ make pypy3

---

Easy threefive

The decode Function

• src decode.py

• threefive.decode is an all purpose function to decode SCTE 35 messages from a file or string.

• MpegTS

import threefive
threefive.decode('/path/to/mpegwithscte35.ts') 

• New in v.2.2.69 threefive.decode can parse MpegTS over http and https

import threefive
threefive.decode('https://futzu.com/xaa.ts') 

• Base64

mesg='/DA4AAAAAAAA///wBQb+AAAAAAAiAiBDVUVJAAAAA3//AAApPWwDDEFCQ0QwMTIzNDU2SBAAAGgCL9A='
threefive.decode(mesg)

• Hex

hexed = "0xFC301100000000000000FFFFFF0000004F253396"
threefive.decode(hexed)

• Read a string directly from a file encoded in Base64, Binary or Hex

$ cat cue.dat
   /DBIAAAAAAAA///wBQb+ek2ItgAyAhdDVUVJSAAAGH+fCAgAAAAALMvDRBEAAAIXQ1VFSUgAABl/nwgIAAAAACyk26AQAACZcuND

from threefive import decode

decode('cue.dat')

---

Advanced threefive

---

Cue Class

• src cue.py
• The threefive.Cue class decodes a SCTE35 binary, base64, or hex encoded string.
• threefive.Cue provides several methods to access the parsed data.

from threefive import Cue

b64 = "/DBIAAAAAAAA///wBQb+ek2ItgAyAhdDVUVJSAAAGH+fCAgAAAAALMvDRBEAAAIXQ1VFSUgAABl/nwgIAAAAACyk26AQAACZcuND"

cue = Cue(b64)
cue.decode()

___https://github.com/futzu/threefive/blob/master/README.md#social-injustice-and-stuff

• A decoded Cue instance contains:

  • cue.info_section

    • 1 threefive.SpliceInfoSection()

  • cue.command

    • 1 of these commands:

      • threefive.BandwidthReservation()
      • threefive.PrivateCommand()
      • threefive.SpliceInsert()
      • threefive.SpliceNull()
      • threefive.TimeSignal()

  • cue.descriptors

    • a list of 0 or more of these descriptors :

      • threefive.AudioDescriptor()
      • threefive.AvailDescriptor()
      • threefive.DtmfDescriptor()
      • threefive.SegmentationDescriptor()
      • threefive.TimeDescriptor()

  • crc

  • 'When parsing SCTE35 Cues from MPEGTS streams, threefive attempts to include as many of the following as possible.'

    • pid of the packet
    • program of the pid
    • pts of the packet
    • preroll ( difference between the packet pts and the pts specified in a TimeSignal or SpliceInsert)

---

• All instance vars can be accessed via dot notation.

>>>> from threefive import Cue
>>>> cue = Cue(b64)
>>>> cue.decode()
True
>>>> cue.command
{'command_length': 5, 'command_type': 6, 'name': 'Time Signal', 'time_specified_flag': True, 'pts_time': 22798.906911}
>>>> cue.command.pts_time
22798.906911
>>>> 

• call one or more of these methods after decode.

Cue Method	Description
cue.get()	returns cue as a dict
cue.get_json()	returns cue as a JSON string
cue.show()	prints cue as JSON

---

• Full Example

from threefive import Cue
b64 = "/DBIAAAAAAAA///wBQb+ek2ItgAyAhdDVUVJSAAAGH+fCAgAAAAALMvDRBEAAAIXQ1VFSUgAABl/nwgIAAAAACyk26AQAACZcuND"
cue.decode(b64)
cue_data = cue.get()

---

Stream Class

 threefive.Stream(tsdata, show_null = False)

• src stream.py

• The threefive.Stream class parses SCTE35 messages from a file or stream.

• Supports

  • Multiple Programs.
  • Multiple SCTE35 Streams.
  • Multi-Packet PMT, and SCTE35 data.
  • Constant Data Parsing.
    • threefive.Stream is designed to run continuously
    • Longest run reported: a single Stream instance parsing video nonstop for 47 days.

• tsdata is an open file handle.

• show_null if set to True, enables showing SCTE 35 null commands.

Method	Description
Stream.show()	Prints Streams that will be checked for SCTE35
Stream.decode(func=show_cue)	Prints SCTE-35 cues for SCTE-35 packets. Accepts an optional function, func, as arg.
Stream.decode_next()	Returns the next SCTE35 cue as a threefive.Cue instance.
Stream.decode_program(the_program=None, func=show_cue)	Same as Stream.decode except only packets where program == the_program
Stream.decode_proxy(func=show_cue)	Same as Stream.decode except raw packets are written to stdout for piping to another program.

Stream.show()

• List programs and streams that will be checked for SCTE35 data.

>>>> from threefive import Stream, version
>>>> version()
'2.2.69'
>>>> with open('video.ts','rb') as tsdata:
....     strm = Stream(tsdata)
....     strm.show()
....     

Program:1030
        PID: 1034(0x40a) Type: 0x6
        PID: 1035(0x40b) Type: 0x86 SCTE35

Program:1100
        PID: 1104(0x450) Type: 0x6
        PID: 1105(0x451) Type: 0x86 SCTE35

Program:1080
        PID: 1084(0x43c) Type: 0x6

Program:1010
        PID: 1014(0x3f6) Type: 0x6
        PID: 1015(0x3f7) Type: 0x86 SCTE35

---

Stream.decode(func=show_cue)

import sys
from threefive import Stream

if __name__ =='__main__':
   with open(sys.argv[1],'rb') as tsdata:
       sp = Stream(tsdata)
       sp.decode()

• Pass in custom function

• func should match the interface func(cue)

import sys
import threefive

def display(cue):
   print(f'\033[92m{cue.packet_data}\033[00m')
   print(f'{cue.command.name}')

def do():
   with open(sys.argv[1],'rb') as tsdata:
    sp = threefive.Stream(tsdata)
    sp.decode(func = display)       

if __name__ == '__main__':
    do()

---

Stream.decode_next()

• Stream.decode_next returns the next SCTE35 cue as a threefive.Cue instance.

import sys
import threefive

def do():
    arg = sys.argv[1]
    with open(arg,'rb') as tsdata:
        st = threefive.Stream(tsdata)
        while True:
            cue = st.decode_next()
            if not cue:
                return False
            if cue:
                cue.show()

if __name__ == "__main__":
    do()

---

Stream.decode_program(the_program, func = show_cue)

• Use Stream.decode_program() instead of Stream.decode() to decode SCTE-35 from packets where program == the_program

import threefive

with open('../35.ts','rb') as tsdata:
    threefive.Stream(tsdata).decode_program(1)

---

Stream.decode_proxy(func = show_cue)

• Writes all packets to sys.stdout.

• Writes scte35 data to sys.stderr.

import threefive

with open('vid.ts','rb') as tsdata:
    sp = threefive.Stream(tsdata)
    sp.proxy_decode()

• Pipe to mplayer

$ python3 proxy.py | mplayer -

---