streamtools/encoding-info

   1 Notations:
   2 ----------
   3 - $(FOO) is to be replaced with value of parameter 'FOO'.
   4 - '> foo' means 'foo' entered from system command line.
   5 - 'JPC-RR> foo' means 'foo' entered from JPC-RR command line (or from autoexec files)
   6 - <...> stands for rest of command (may vary).
   7 - 'raw FOO dump' is what comes out of emulator
   8 - 'raw FOO data' is headerless uncompressed data suitable for direct encoder input.
   9
  10
  11 Use of named FIFOs:
  12 -------------------
  13 FIFOs may be used for most data in order to save space.
  14
  15 Note that if multiple input streams are mixed or muxed togeter, at least all but one of them should
  16 have unbounded buffering capability in order to avoid deadlocks. The streams output by emulator
  17 are not buffered. If all input streams to stream processing operation have unbounded buffering, the
  18 output has too.
  19
  20 The usual way to implement unbounded buffering is to save the data to disk. Also, because video data
  21 is the largest, it is usually wise to pick video data as the only stream that isn't buffered (is
  22 fully streamed).
  23
  24
  25 Dumping video:
  26 --------------
  27
  28 Video can be dumped using org.jpc.plugins.RAWVideoDumper plugin. It takes comma seperated list
  29 of parametername=value pairs.
  30
  31 Parameters:
  32 - rawoutput (required): File or FIFO to dump the raw video dump to.
  33
  34 E.g:
  35
  36 JPC-RR> load org.jpc.plugins.RAWVideoDumper(rawoutput=video.dump)
  37
  38 Note that dumper should be loaded before PCControl/PCRunner plugin is loaded, or it may not
  39 attach properly.
  40
  41
  42 Dumping audio:
  43 --------------
  44
  45 Audio can be dumped using org.jpc.plugins.RAWVideoDumper plugin. It takes comma seperated list
  46 of parametername=value pairs.
  47
  48 Parameters:
  49 - file (required): File or FIFO to dump the raw audio dump to.
  50 - src (required): Stream source name. In form '<classname>-<outputnumber>'. <classname> is class
  51   name of sound source, <outputnumer> is number of output for that class. First output is 0, next
  52   is 1, and so on.
  53 - offset (optional): Number of nanoseconds to delay audio (default: no delay). Useful to make
  54   gap for prepending something silent to video.
  55
  56 E.g:
  57
  58 JPC-RR> load org.jpc.plugins.RAWVideoDumper(file=video.dump,src=org.jpc.emulator.peripheral.PCSpeaker-0,offset=1500000000)
  59
  60 Note that dumper should be loaded before PCControl/PCRunner plugin is loaded, or it may not
  61 attach properly.
  62
  63
  64 Concatenating raw video/audio dump segments:
  65 --------------------------------------------
  66
  67 Raw video/audio dump segments may be concatented by just concatenating the streams (e.g. using 'cat'
  68 utility). This is useful for prepending fixed segments to videos without wasting disk space.
  69
  70 Same trick works with raw audio/video data if sampling rate / frame size / framerate matches.
  71
  72
  73 Converting raw video dump data to raw video data:
  74 -------------------------------------------------
  75
  76 > rawtorgb.exe $(INPUT) $(OUTPUT) $(WIDTH) $(HEIGHT) $(FRAMEGAP)
  77
  78 This tool reads raw video dump from $(INPUT) and writes raw video data to $(OUTPUT). The written frames
  79 are $(WIDTH)x$(HEIGHT) in size, and are resized to that size if needed (the aspect ratio is always, 4:3).
  80
  81 The raw video data is raw 32-bit, 8 bits per channel RGBx, left-to-right, top-to-bottom, past-to-future.
  82
  83 $(FRAMEGAP) gives interfame time in nanoseconds (e.g. 16666667 for 60fps).
  84
  85
  86 Converting raw audio dump data to raw audio data:
  87 -------------------------------------------------
  88
  89 > rawtoaudio.exe $(INPUT) $(OUTPUT) $(SAMPLERATE)
  90
  91 This tool reads raw audio dump from $(INPUT) and writes raw audio data to $(OUTPUT). The written data
  92 uses sampling rate of $(SAMPLERATE).
  93
  94 The raw audio data is 16-bit stereo signed little-endian PCM.
  95
  96
  97 Filtering audio data:
  98 ---------------------
  99 Filtering audio data is usually not needed, but it is very useful if dealing with "digital audio"
 100 from PC-speaker (some stuff uses that). In case of PC speaker, the sampling frequency should be notched
 101 out (or it appears as very annoying whine). Any noncausal linear digital IIR filter (the denominator
 102 must be causal) can be appiled. Filtering is usually done between converting to raw data and mixing.
 103
 104 > audiofilter.exe $(INPUT) $(OUTPUT) $(FILTERCOEFFICIENTS)
 105
 106 This tool reads raw audio data from $(INPUT) and writes raw audio data to $(OUTPUT).
 107 Filter coefficients are series of floating point numbers, the order is from lesser indexes (less delay/
 108 more advance) to greater indexes (greater delay). The coefficents may be prefixed with:
 109
 110 '#': Marks that this coefficent is b0 (numerator no-delay coefficient). If none is marked such, first
 111      unprefixed coefficient is assumed to be b0 (specify only at most once, or results are unpredictable).
 112 '/': Marks that this coefficent is from a-series (denumerator coefficients), not b-series (numerator
 113      coefficients).
 114
 115 The numerator coefficients start from b0 if no coefficient is marked with '#', otherwise from coefficient
 116 that makes marked coefficent b0. Denumerator coefficients start from a0 (the coefficient of current
 117 output sample)
 118
 119 If no coefficient is marked to belong to denumerator, command behaves like single '/1' (a0 = 1, others
 120 zero i.e, FIR filtering) was given.
 121
 122 Filter can also adjust audio volume:
 123
 124 > audiofilter.exe $(INPUT) $(OUTPUT) $(VOLUME)
 125
 126 The $(VOLUME) is positive number in this case that gives the volume adjustment. 0 is silence, 0.5 is
 127 half volume, 1 is original volume, 2 is double volume and so on (any positive float can be used).
 128
 129 This volume changing is useful to avoid overrunning dynamic range during mixing.
 130
 131
 132 Mixing audio data:
 133 ------------------
 134 If there are multiple audio streams, they need to be mixed together. The mixed streams need to have
 135 the same sample rate. Mixing should come after filtering (if any) and comes after dump to data
 136 conversion.
 137
 138 > audiomix.exe $(OUTPUT) $(INPUTS)
 139
 140 Note that the inputs are "wrong" way around. This command writes into $(OUTPUT) the raw audio data
 141 from mixing of inputs $(INPUTS) (one or more raw audio data streams).
 142
 143
 144 Reading raw audio data using Gstreamer:
 145 ---------------------------------------
 146
 147 > gst-launch filesrc location=$(INPUT) ! audioparse format=int rate=$(RATE) width=16 depth=16 signed=true endianness=1234 channels=2 ! audioconvert ! <...>
 148
 149 (you need gst-plugins-bad for audioparse). This reads raw audio data from $(INPUT), assuming sample
 150 rate to be $(RATE). Replace <...> with suitable encoder to encode it, muxer to mux it and filesink
 151 to write the result to disk.
 152
 153 Assuming defaults don't change, you can probably get away with:
 154
 155 > gst-launch filesrc location=$(INPUT) ! audioparse format=int rate=$(RATE) ! audioconvert ! <...>
 156
 157 Reading Raw video data using Gstreamer:
 158 ---------------------------------------
 159
 160 > gst-launch filesrc location=$(INPUT) ! videoparse format=6 width=$(WIDTH) height=$(HEIGHT) framerate=$(FRAMERATE) ! ffmpegcolorspace ! <...>
 161
 162 (you need gst-plugins-bad for videoparse). This reads raw video data from $(INPUT), assuming frame
 163 rate to be $(FRAMERATE) and frame size be $(WIDTH)x$(HEIGHT)
 164