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 video 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 > rawtoaudio2.exe --input-file=$(INPUT) --output-file=$(OUTPUT) --output-rate=$(SAMPLERATE) --input-format=(fm|pcm) --output-format=wav
  90
  91 This tool reads raw audio dump from $(INPUT) and writes raw audio data to $(OUTPUT). The written data
  92 is in WAV format. Use --input-format=fm for FM dump data and --input-format=pcm for PCM dump data.
  93
  94 The raw audio data is 16-bit stereo signed little-endian PCM.
  95
  96 Filtering audio data:
  97 ---------------------
  98 Filtering audio data is usually not needed, but it is very useful if dealing with "digital audio"
  99 from PC-speaker (some stuff uses that). In case of PC speaker, the sampling frequency should be notched
 100 out (or it appears as very annoying whine). Any causal linear digital IIR filter can be appiled.
 101
 102 Filtering can be specified by --output-filter=$(FILTERCOEFFICIENTS) to rawtoaudio2.exe.
 103
 104 Filter coefficients are series of floating point numbers, separated by ','. the order is from lesser
 105 indexes (less delay) to greater indexes (more delay). The coefficents may be prefixed with:
 106
 107 '/': Marks that this coefficent is from a-series (denumerator coefficients), not b-series (numerator
 108      coefficients).
 109
 110 The numerator coefficients start from b0 (current sample). Denumerator coefficients start from a0 (the
 111 coefficient of current output sample)
 112
 113 If no coefficient is marked to belong to denumerator, command behaves like single '/1' (a0 = 1, others
 114 zero i.e, FIR filtering) was given.
 115
 116 Filter can also adjust audio volume:
 117
 118 --output-gain=<db-gain>
 119 --output-attanuation=<db-attenuation>
 120
 121 This volume changing is useful to avoid overrunning dynamic range during mixing.
 122
 123 Mixing audio data:
 124 ------------------
 125 If there are multiple audio streams, they need to be mixed together. Use your favorite tool (e.g. Sox)
 126 for that.
 127
 128 Reading Raw video data using Gstreamer:
 129 ---------------------------------------
 130
 131 > gst-launch filesrc location=$(INPUT) ! videoparse format=6 width=$(WIDTH) height=$(HEIGHT) framerate=$(FRAMERATE) ! ffmpegcolorspace ! <...>
 132
 133 (you need gst-plugins-bad for videoparse). This reads raw video data from $(INPUT), assuming frame
 134 rate to be $(FRAMERATE) and frame size be $(WIDTH)x$(HEIGHT)
 135