timecode

README

go-timecode

A Go library for parsing and manipulating SMPTE timecodes and frame rates.

Development of this library is very test-driven to ensure accuracy of the frame and timecode calculations. If you'd like to contribute to this library, adding additional useful test cases is a great place to start!

Installation

go get github.com/spiretechnology/go-timecode

Usage Examples

Parse a timecode (drop frame)

tc, err := timecode.Parse("00:01:02;23", timecode.Rate_29_97)
tc.String() // => 00:01:02;23
tc.Frame() // => 1881

Parse a timecode (non-drop frame)

tc, err := timecode.Parse("00:01:02:23", timecode.Rate_24)
tc.String() // => 00:01:02:23
tc.Frame() // => 1511

Create a timecode from a frame count

tc := timecode.FromFrame(1511, timecode.Rate_24, false /* non-drop frame */)
tc.String() // => 00:01:02:23
tc.Frame() // => 1511

Algebra with timecodes and frames

tc, err := timecode.Parse("00:01:02:23", timecode.Rate_24)
tc = tc.Add(timecode.Frame(3))
tc.String() // => 00:01:03:02
tc.Frame() // => 1514

Note: parsing timecodes that don't exist in drop frame

Drop frame timecodes skip the first 2 frames of each minute, unless the minute is a multiple of 10. This changes to the first 4 frames of each minute if the frame rate is 59.94.

For instance, in 29.97, the timecode 00:00:59:29 is immediately followed by 00:01:00:02. Two timecodes were dropped: 00:01:00:00 and 00:01:00:01

Those dropped timecodes don't correspond to any actual frame number, and so we need to choose how to resolve those frames. The choice we have made with this library is to round up the next valid frame. If you try to parse 00:01:00:00, the result will be rounded up to 00:01:00:02, which is the next valid frame in the sequence.

Contributing

We welcome contributions that make this library more reliable. To add test cases, fix bugs, or anything else, please submit a pull request.

Other resources

• spiretechnology/js-timecode - A TypeScript / JavaScript library for parsing and manipulating SMPTE timecodes and frame rates.

Documentation

Index

• Variables
• type Components
  • func (c Components) Equals(other Components) bool
• type Frame
  • func (f Frame) Add(other Framer) Frame
  • func (f Frame) Equals(other Framer) bool
  • func (f Frame) Frame() int64
• type Framer
• type Rate
  • func ParseRate(str string) (Rate, bool)
  • func RateFromFraction(num, den int) Rate
  • func (r *Rate) String() string
• type Timecode
  • func FromComponents(components Components, rate Rate, dropFrame bool) *Timecode
  • func FromFrame(frame int64, rate Rate, dropFrame bool) *Timecode
  • func MustParse(timecode string, rate Rate) *Timecode
  • func Parse(timecode string, rate Rate) (*Timecode, error)
  • func (t *Timecode) Add(other Framer) *Timecode
  • func (t *Timecode) AddFrames(other int64) *Timecode
  • func (t *Timecode) Components() Components
  • func (t *Timecode) Equals(other Framer) bool
  • func (t *Timecode) Frame() int64
  • func (t *Timecode) String() string

Variables

var (
	Rate_23_976 = Rate{"23.976", 24, 0, 24000, 1001}
	Rate_24     = Rate{"24", 24, 0, 24, 1}
	Rate_30     = Rate{"30", 30, 0, 30, 1}
	Rate_29_97  = Rate{"29.97", 30, 2, 30000, 1001}
	Rate_60     = Rate{"60", 60, 0, 60, 1}
	Rate_59_94  = Rate{"59.94", 60, 4, 60000, 1001}
)

var TimecodeRegex = regexp.MustCompile(`^(\d\d)(:|;)(\d\d)(:|;)(\d\d)(:|;)(\d+)$`)

TimecodeRegex is the pattern for a valid SMPTE timecode

Types

type Components

type Components struct {
	Hours, Minutes, Seconds, Frames int64
}

func (Components) Equals

func (c Components) Equals(other Components) bool

type Frame

type Frame int64

Frame type represents a specific frame index within some media content

func (Frame) Add

func (f Frame) Add(other Framer) Frame

Add adds another framer instance to this frame

func (Frame) Equals

func (f Frame) Equals(other Framer) bool

Equals checks if this framer is equal to the other

func (Frame) Frame

func (f Frame) Frame() int64

Frame gets the frame index for this frame. In this case, it just returns itself

type Framer

type Framer interface {
	Frame() int64
}

Framer defines the interface for something that can be converted into a specific frame index. Currently, this is limited only to Frame and Timecode

type Rate

type Rate struct {
	Str      string
	Nominal  int
	Drop     int
	Num, Den int
}

Rate represents a frame rate for a timecode

func ParseRate

func ParseRate(str string) (Rate, bool)

ParseRate returns a Rate from a string representation.

func RateFromFraction

func RateFromFraction(num, den int) Rate

RateFromFraction returns a Rate from a numerator and denominator.

func (*Rate) String

func (r *Rate) String() string

String creates a string representation of the rate

type Timecode

type Timecode struct {
	// contains filtered or unexported fields
}

Timecode represents a timecode value, either as a duration or a specific point in time

func FromComponents

func FromComponents(components Components, rate Rate, dropFrame bool) *Timecode

func FromFrame

func FromFrame(frame int64, rate Rate, dropFrame bool) *Timecode

func MustParse

func MustParse(timecode string, rate Rate) *Timecode

MustParse parses a timecode from a string, and treats it using the provided frame rate value

func Parse

func Parse(timecode string, rate Rate) (*Timecode, error)

Parse parses a timecode from a string, and treats it using the provided frame rate value

func (*Timecode) Add

func (t *Timecode) Add(other Framer) *Timecode

Add adds another framer instance to this timecode

func (*Timecode) AddFrames

func (t *Timecode) AddFrames(other int64) *Timecode

func (*Timecode) Components

func (t *Timecode) Components() Components

Components gets the components of the timecode: hours, minutes, seconds, frames.

func (*Timecode) Equals

func (t *Timecode) Equals(other Framer) bool

Equals checks if this timecode is equal to another framer

func (*Timecode) Frame

func (t *Timecode) Frame() int64

Frame gets the frame index for this timecode

func (*Timecode) String

func (t *Timecode) String() string

String creates a string representation for the timecode