doc: extensive alignment of top-levle documentation for all packages.

Extension .m4s is now interpreted as mp4 file in mp4ff-pslister.

CHANGELOG.md

@@ -13,13 +13,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - PrftBox Info output
 - Removed ReplaceChild method of StsdBox
 - CreateHdlr name for timed metadata
+- extension .m4s is interpreted as MP4 file in mp4ff-pslister
 
 ### Added
 
 - NTP64 struct with methods to convert to time.Time
 - Constants for PrftBox flags
-- Unittest to all commands and examples
-
+- Unittest to all programs in [cmd](cmd) and [examples](examples).
+- Documentation in doc.go files for all packages
 
 ### Fixed
 

Makefile

@@ -12,9 +12,9 @@ mp4ff-crop mp4ff-decrypt mp4ff-encrypt mp4ff-info mp4ff-nallister mp4ff-pslister
 	go build -ldflags "-X github.com/Eyevinn/mp4ff/mp4.commitVersion=$$(git describe --tags HEAD) -X github.com/Eyevinn/mp4ff/mp4.commitDate=$$(git log -1 --format=%ct)" -o out/$@ ./cmd/$@/main.go
 
 .PHONY: examples
-examples: initcreator multitrack resegmenter segmenter
+examples: add-sidx combine-segs initcreator multitrack resegmenter segmenter
 
-initcreator multitrack resegmenter segmenter:
+add-sidx combine-segs initcreator multitrack resegmenter segmenter:
 	go build -o examples-out/$@  ./examples/$@
 
 .PHONY: test
@@ -25,6 +25,12 @@ test: prepare
 testsum: prepare
 	gotestsum
 
+.PHONY: open-docs
+open-docs:
+	echo "If needed: go install golang.org/x/pkgsite/cmd/pkgsite@latest"
+	pkgsite -http localhost:9999
+	# open http://localhost:9999/pkg/github.com/Eyevinn/mp4ff/
+
 .PHONY: coverage
 coverage:
 	# Ignore (allow) packages without any tests

aac/doc.go

@@ -1,4 +1,4 @@
 /*
-Package aac - parse and generate AAC meta data including ADTS headers.
+Package aac parses and generates AAC meta data including ADTS headers.
 */
 package aac

av1/doc.go

@@ -1,4 +1,4 @@
 /*
-Package av1 -  parsing of av1 AV1CodecConfigurationRecord.
+Package av1 decodes (parses) and encodes (writes) AV1 CodecConfigurationRecord.
 */
 package av1

avc/doc.go

@@ -1,4 +1,4 @@
 /*
-Package avc -  parse AVC(H.264) NAL unit headers, slice headers and complete SPS and PPS.
+Package avc parses AVC (H.264) NAL unit headers, slice headers and complete SPS and PPS.
 */
 package avc

bits/doc.go

@@ -1,9 +1,17 @@
 /*
-Package bits - bit and bytes reading and writing including Golomb codes and EBSP.
+Package bits provides bit and bytes reading and writing including Golomb codes and EBSP as used by MPEG video standards.
 All readers and writers accumulate errors in the sense that they will stop reading or writing at the first error.
-The first error, if any, can be retrieved with AccError().
+The first error, if any, can be retrieved with an AccError() method.
 
-Beyond plain bit reading and writing, reading and writing of ebsp (Encapsulated Byte Sequence Packets) is supported.
-EBSP uses insertion of start-code emulation prevention bytes 0x03 and is used in MPEG video standards from AVC (H.264) and forward.
+EBSP (Encapsulated Byte Sequence Packets) uses insertion of start-code emulation prevention bytes 0x03 and is
+used in MPEG video standards from AVC (H.264) and forward. The main types are:
+
+  - [Reader] reads bits and bytes from an underlying [io.Reader] with accumulated error
+  - [Writer] writes bits and bytes to an underlying [io.Writer] with accumulated error
+  - [EBSPReader] reads EBSP from an underlying [io.Reader] with accumulated error
+  - [EBSPWriter] writes EBSP to an underlying [io.Writer] with accumulated error
+  - [ByteWriter] writes byte-based structures to an underlying [io.Writer] with accumulated error
+  - [FixedSliceReader] reads various byte-based structures from a fixed slice with accumulated error
+  - [FixedSliceWriter] writes various byte-based structures to a fixed slice with accumulated error
 */
 package bits

cmd/doc.go

@@ -1,12 +1,15 @@
 /*
-Package cmd - command line tools built using mp4ff.
+Package cmd provides command line tools built using mp4ff.
 
 Install like
 
 	go install ./...
 
-or remotely as
+or directly from the repo
+as
 
-	go get -u github.com/Eyevinn/mp4ff/cmd/mp4ff-info
+	go install github.com/Eyevinn/mp4ff/cmd/mp4ff-info
+	go install github.com/Eyevinn/mp4ff/cmd/mp4ff-subslister
+	...
 */
 package cmd

cmd/mp4ff-crop/doc.go

@@ -0,0 +1,17 @@
+/*
+mp4ff-crop crops a (progressive) mp4 file to just before a sync frame after specified number of milliseconds.
+The goal is to leave the file structure intact except for cropping of samples and
+moving mdat to the end of the file, if not already there.
+
+	Usage of mp4ff-crop:
+
+		mp4ff-crop [options] <inFile> <outFile>
+
+	options:
+
+		-d uint
+			Duration in milliseconds (default 1000)
+		-version
+			Get mp4ff version
+*/
+package main

cmd/mp4ff-crop/main.go

@@ -1,8 +1,3 @@
-/*
-mp4ff-crop crops a (progressive) mp4 file to just before a sync frame after specified number of milliseconds.
-The intension is that the structure of the file shall be left intact except for cropping of samples and
-moving mdat to the end of the file, if not already there.
-*/
 package main
 
 import (
@@ -20,11 +15,11 @@ const (
 	appName = "mp4ff-crop"
 )
 
-var usg = `Usage of %s:
-
-%s crops a (progressive) mp4 file to just before a sync frame after specified number of milliseconds.
+var usg = `%s crops a (progressive) mp4 file to just before a sync frame after specified number of milliseconds.
 The goal is to leave the file structure intact except for cropping of samples and
 moving mdat to the end of the file, if not already there.
+
+Usage of %s:
 `
 
 type options struct {
@@ -61,7 +56,6 @@ func run(args []string, stdout io.Writer) error {
 
 	if err != nil {
 		if errors.Is(err, flag.ErrHelp) {
-			fs.Usage()
 			return nil
 		}
 		return err

cmd/mp4ff-crop/main_test.go

@@ -21,6 +21,7 @@ func TestCommandLines(t *testing.T) {
 		{desc: "unknown args", args: []string{appName, "-x"}, expectedErr: true},
 		{desc: "duration = 0", args: []string{appName, "-d", "0", "dummy.mp4", "dummy.mp4"}, expectedErr: true},
 		{desc: "non-existing infile", args: []string{appName, "-d", "1000", "notExists.mp4", "dummy.mp4"}, expectedErr: true},
+		{desc: "bad infile", args: []string{appName, "-d", "1000", "main.go", "dummy.mp4"}, expectedErr: true},
 	}
 	for _, c := range cases {
 		t.Run(c.desc, func(t *testing.T) {

cmd/mp4ff-decrypt/doc.go

@@ -0,0 +1,18 @@
+/*
+mp4ff-decrypt decrypts a fragmented mp4 file encrypted with Common Encryption scheme cenc or cbcs.
+For a media segment, it needs an init segment with encryption information.
+
+	    Usage of mp4ff-decrypt:
+
+	        mp4ff-decrypt [options] infile outfile
+
+	    options:
+
+		    -init string
+		  	    Path to init file with encryption info (scheme, kid, pssh)
+		    -k string
+		     	Required: key (hex)
+		    -version
+		  	    Get mp4ff version
+*/
+package main

cmd/mp4ff-decrypt/main.go

@@ -1,4 +1,3 @@
-// mp4ff-decrypt decrypts a fragmented mp4 file encrypted with Common Encryption scheme cenc or cbcs.
 package main
 
 import (
@@ -16,11 +15,10 @@ const (
 	appName = "mp4ff-decrypt"
 )
 
-var usg = `Usage of %s:
-
-%s decrypts a fragmented mp4 file encrypted with Common Encryption scheme cenc or cbcs.
+var usg = `%s decrypts a fragmented mp4 file encrypted with Common Encryption scheme cenc or cbcs.
 For a media segment, it needs an init segment with encryption information.
 
+Usage of %s:
 `
 
 type options struct {
@@ -57,7 +55,6 @@ func run(args []string) error {
 
 	if err != nil {
 		if errors.Is(err, flag.ErrHelp) {
-			fs.Usage()
 			return nil
 		}
 		return err

cmd/mp4ff-decrypt/main_test.go

@@ -24,8 +24,9 @@ func TestNonRunningOptionCases(t *testing.T) {
 		{desc: "unknown args", args: []string{"mp4ff-decrypt", "-x"}, err: true},
 		{desc: "no outfile", args: []string{"mp4ff-decrypt", "infile.mp4"}, err: true},
 		{desc: "no key", args: []string{"mp4ff-decrypt", "infile.mp4", outFile}, err: true},
-		{desc: "bad infile", args: []string{"mp4ff-decrypt", "-k", key, "infile.mp4", outFile}, err: true},
-		{desc: "bad initfile", args: []string{"mp4ff-decrypt", "-init", "init.mp4", "-k", key, infile, outFile}, err: true},
+		{desc: "non-existing infile", args: []string{"mp4ff-decrypt", "-k", key, "infile.mp4", outFile}, err: true},
+		{desc: "non-existing initfile", args: []string{"mp4ff-decrypt", "-init", "init.mp4", "-k", key, infile, outFile}, err: true},
+		{desc: "bad infile", args: []string{"mp4ff-decrypt", "-k", key, "main.go", outFile}, err: true},
 		{desc: "short key", args: []string{"mp4ff-decrypt", "-k", "ab", infile, outFile}, err: true},
 		{desc: "bad key", args: []string{"mp4ff-decrypt", "-k", badKey, infile, outFile}, err: true},
 		{desc: "non-encrypted file", args: []string{"mp4ff-decrypt", "-k", key, nonEncryptedFile, outFile}, err: false},

cmd/mp4ff-encrypt/doc.go

@@ -0,0 +1,27 @@
+/*
+mp4ff-encrypt encrypts a fragmented mp4 file using Common Encryption with cenc or cbcs scheme.
+A combined fragmented file with init segment and media segment(s) will be encrypted.
+For a pure media segment, an init segment with encryption information is needed
+
+	Usage of mp4ff-encrypt:
+
+	    mp4ff-encrypt [options] infile outfile
+
+	options:
+
+		-init string
+		      Path to init file with encryption info (scheme, kid, pssh)
+		-iv string
+		      Required: iv (16 or 32 hex chars)
+		-key string
+		      Required: key (32 hex chars)
+		-kid string
+		      key id (32 hex chars). Required if initFilePath empty
+		-pssh string
+		      file with one or more pssh box(es) in binary format. Will be added at end of moov box
+		-scheme string
+		      cenc or cbcs. Required if initFilePath empty (default "cenc")
+		-version
+		      Get mp4ff version
+*/
+package main

cmd/mp4ff-encrypt/main.go

@@ -1,4 +1,3 @@
-// mp4ff-encrypt encrypts a fragmented mp4 file using Common Encryption using cenc or cbcs scheme.
 package main
 
 import (
@@ -16,12 +15,11 @@ const (
 	appName = "mp4ff-encrypt"
 )
 
-var usg = `Usage of %s:
-
-%s encrypts a fragmented mp4 file using Common Encryption with cenc or cbcs scheme.
+var usg = `%s encrypts a fragmented mp4 file using Common Encryption with cenc or cbcs scheme.
 A combined fragmented file with init segment and media segment(s) will be encrypted.
 For a pure media segment, an init segment with encryption information is needed.
 
+Usage of %s:
 `
 
 type options struct {
@@ -68,7 +66,6 @@ func run(args []string) error {
 
 	if err != nil {
 		if errors.Is(err, flag.ErrHelp) {
-			fs.Usage()
 			return nil
 		}
 		return err

cmd/mp4ff-encrypt/main_test.go

@@ -39,6 +39,9 @@ func TestOptionCases(t *testing.T) {
 		{desc: "non-existing initFile",
 			args: []string{appName, "-key", key, "-iv", iv, "-init", "init.mp4", inSeg, outFile},
 			err:  true},
+		{desc: "bad initFile",
+			args: []string{appName, "-key", key, "-iv", iv, "-init", "main.go", inSeg, outFile},
+			err:  true},
 		{desc: "too short iv ",
 			args: []string{appName, "-key", key, "-iv", "00", "-init", init, inSeg, outFile},
 			err:  true},

cmd/mp4ff-info/doc.go

@@ -0,0 +1,15 @@
+/*
+mp4ff-info prints the box tree of input mp4 (ISOBMFF) file.
+
+	Usage of mp4ff-info:
+
+		mp4ff-info [options] infile
+
+	options:
+
+		-l string
+			level of details, e.g. all:1 or trun:1,subs:1
+		-version
+			Get mp4ff version
+*/
+package main

cmd/mp4ff-info/main.go

@@ -1,10 +1,10 @@
-// mp4ff-info prints the box tree of input mp4 (ISOBMFF) file.
 package main
 
 import (
 	"errors"
 	"flag"
 	"fmt"
+	"io"
 	"os"
 
 	"github.com/Eyevinn/mp4ff/mp4"
@@ -14,9 +14,9 @@ const (
 	appName = "mp4ff-info"
 )
 
-var usg = `Usage of %s:
+var usg = `%s prints the box tree of input mp4 (ISOBMFF) file.
 
-%s prints the box tree of input mp4 (ISOBMFF) file.
+Usage of %s:
 `
 
 type options struct {
@@ -41,19 +41,18 @@ func parseOptions(fs *flag.FlagSet, args []string) (*options, error) {
 }
 
 func main() {
-	if err := run(os.Args); err != nil {
+	if err := run(os.Args, os.Stdout); err != nil {
 		fmt.Fprintf(os.Stderr, "error: %v\n", err)
 		os.Exit(1)
 	}
 }
 
-func run(args []string) error {
+func run(args []string, w io.Writer) error {
 	fs := flag.NewFlagSet(appName, flag.ContinueOnError)
 	opts, err := parseOptions(fs, args)
 
 	if err != nil {
 		if errors.Is(err, flag.ErrHelp) {
-			fs.Usage()
 			return nil
 		}
 		return err
@@ -79,7 +78,7 @@ func run(args []string) error {
 	if err != nil {
 		return fmt.Errorf("could not parse input file: %w", err)
 	}
-	err = parsedMp4.Info(os.Stdout, opts.levels, "", "  ")
+	err = parsedMp4.Info(w, opts.levels, "", "  ")
 	if err != nil {
 		return fmt.Errorf("could not print info: %w", err)
 	}