Encoder firmware API description ================================ ------------------------------------------------------------------------------- Name CX2341X_ENC_PING_FW Enum 128/0x80 Description Does nothing. Can be used to check if the firmware is responding. ------------------------------------------------------------------------------- Name CX2341X_ENC_START_CAPTURE Enum 129/0x81 Description Commences the capture of video, audio and/or VBI data. All encoding parameters must be initialized prior to this API call. Captures frames continuously or until a predefined number of frames have been captured. Param[0] Capture stream type: 0=MPEG 1=Raw 2=Raw passthrough 3=VBI Param[1] Bitmask: Bit 0 when set, captures YUV Bit 1 when set, captures PCM audio Bit 2 when set, captures VBI (same as param[0]=3) Bit 3 when set, the capture destination is the decoder (same as param[0]=2) Bit 4 when set, the capture destination is the host Note: this parameter is only meaningful for RAW capture type. ------------------------------------------------------------------------------- Name CX2341X_ENC_STOP_CAPTURE Enum 130/0x82 Description Ends a capture in progress Param[0] 0=stop at end of GOP (generates IRQ) 1=stop immediate (no IRQ) Param[1] Stream type to stop, see param[0] of API 0x81 Param[2] Subtype, see param[1] of API 0x81 ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_AUDIO_ID Enum 137/0x89 Description Assigns the transport stream ID of the encoded audio stream Param[0] Audio Stream ID ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_VIDEO_ID Enum 139/0x8B Description Set video transport stream ID Param[0] Video stream ID ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_PCR_ID Enum 141/0x8D Description Assigns the transport stream ID for PCR packets Param[0] PCR Stream ID ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_FRAME_RATE Enum 143/0x8F Description Set video frames per second. Change occurs at start of new GOP. Param[0] 0=30fps 1=25fps ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_FRAME_SIZE Enum 145/0x91 Description Select video stream encoding resolution. Param[0] Height in lines. Default 480 Param[1] Width in pixels. Default 720 ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_BIT_RATE Enum 149/0x95 Description Assign average video stream bitrate. Note on the last three params: Param[3] and [4] seem to be always 0, param [5] doesn't seem to be used. Param[0] 0=variable bitrate, 1=constant bitrate Param[1] bitrate in bits per second Param[2] peak bitrate in bits per second, divided by 400 Param[3] Mux bitrate in bits per second, divided by 400. May be 0 (default). Param[4] Rate Control VBR Padding Param[5] VBV Buffer used by encoder ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_GOP_PROPERTIES Enum 151/0x97 Description Setup the GOP structure Param[0] GOP size (maximum is 34) Param[1] Number of B frames between the I and P frame, plus 1. For example: IBBPBBPBBPBB --> GOP size: 12, number of B frames: 2+1 = 3 Note that GOP size must be a multiple of (B-frames + 1). ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_ASPECT_RATIO Enum 153/0x99 Description Sets the encoding aspect ratio. Changes in the aspect ratio take effect at the start of the next GOP. Param[0] '0000' forbidden '0001' 1:1 square '0010' 4:3 '0011' 16:9 '0100' 2.21:1 '0101' reserved .... '1111' reserved ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_DNR_FILTER_MODE Enum 155/0x9B Description Assign Dynamic Noise Reduction operating mode Param[0] Bit0: Spatial filter, set=auto, clear=manual Bit1: Temporal filter, set=auto, clear=manual Param[1] Median filter: 0=Disabled 1=Horizontal 2=Vertical 3=Horiz/Vert 4=Diagonal ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_DNR_FILTER_PROPS Enum 157/0x9D Description These Dynamic Noise Reduction filter values are only meaningful when the respective filter is set to "manual" (See API 0x9B) Param[0] Spatial filter: default 0, range 0:15 Param[1] Temporal filter: default 0, range 0:31 ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_CORING_LEVELS Enum 159/0x9F Description Assign Dynamic Noise Reduction median filter properties. Param[0] Threshold above which the luminance median filter is enabled. Default: 0, range 0:255 Param[1] Threshold below which the luminance median filter is enabled. Default: 255, range 0:255 Param[2] Threshold above which the chrominance median filter is enabled. Default: 0, range 0:255 Param[3] Threshold below which the chrominance median filter is enabled. Default: 255, range 0:255 ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_SPATIAL_FILTER_TYPE Enum 161/0xA1 Description Assign spatial prefilter parameters Param[0] Luminance filter 0=Off 1=1D Horizontal 2=1D Vertical 3=2D H/V Separable (default) 4=2D Symmetric non-separable Param[1] Chrominance filter 0=Off 1=1D Horizontal (default) ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_VBI_LINE Enum 183/0xB7 Description Selects VBI line number. Param[0] Bits 0:4 line number Bit 31 0=top_field, 1=bottom_field Bits 0:31 all set specifies "all lines" Param[1] VBI line information features: 0=disabled, 1=enabled Param[2] Slicing: 0=None, 1=Closed Caption Almost certainly not implemented. Set to 0. Param[3] Luminance samples in this line. Almost certainly not implemented. Set to 0. Param[4] Chrominance samples in this line Almost certainly not implemented. Set to 0. ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_STREAM_TYPE Enum 185/0xB9 Description Assign stream type Note: Transport stream is not working in recent firmwares. And in older firmwares the timestamps in the TS seem to be unreliable. Param[0] 0=Program stream 1=Transport stream 2=MPEG1 stream 3=PES A/V stream 5=PES Video stream 7=PES Audio stream 10=DVD stream 11=VCD stream 12=SVCD stream 13=DVD_S1 stream 14=DVD_S2 stream ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_OUTPUT_PORT Enum 187/0xBB Description Assign stream output port. Normally 0 when the data is copied through the PCI bus (DMA), and 1 when the data is streamed to another chip (pvrusb and cx88-blackbird). Param[0] 0=Memory (default) 1=Streaming 2=Serial Param[1] Unknown, but leaving this to 0 seems to work best. Indications are that this might have to do with USB support, although passing anything but 0 only breaks things. ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_AUDIO_PROPERTIES Enum 189/0xBD Description Set audio stream properties, may be called while encoding is in progress. Note: all bitfields are consistent with ISO11172 documentation except bits 2:3 which ISO docs define as: '11' Layer I '10' Layer II '01' Layer III '00' Undefined This discrepancy may indicate a possible error in the documentation. Testing indicated that only Layer II is actually working, and that the minimum bitrate should be 192 kbps. Param[0] Bitmask: 0:1 '00' 44.1Khz '01' 48Khz '10' 32Khz '11' reserved 2:3 '01'=Layer I '10'=Layer II 4:7 Bitrate: Index | Layer I | Layer II ------+-------------+------------ '0000' | free format | free format '0001' | 32 kbit/s | 32 kbit/s '0010' | 64 kbit/s | 48 kbit/s '0011' | 96 kbit/s | 56 kbit/s '0100' | 128 kbit/s | 64 kbit/s '0101' | 160 kbit/s | 80 kbit/s '0110' | 192 kbit/s | 96 kbit/s '0111' | 224 kbit/s | 112 kbit/s '1000' | 256 kbit/s | 128 kbit/s '1001' | 288 kbit/s | 160 kbit/s '1010' | 320 kbit/s | 192 kbit/s '1011' | 352 kbit/s | 224 kbit/s '1100' | 384 kbit/s | 256 kbit/s '1101' | 416 kbit/s | 320 kbit/s '1110' | 448 kbit/s | 384 kbit/s Note: For Layer II, not all combinations of total bitrate and mode are allowed. See ISO11172-3 3-Annex B, Table 3-B.2 8:9 '00'=Stereo '01'=JointStereo '10'=Dual '11'=Mono Note: the cx23415 cannot decode Joint Stereo properly. 10:11 Mode Extension used in joint_stereo mode. In Layer I and II they indicate which subbands are in intensity_stereo. All other subbands are coded in stereo. '00' subbands 4-31 in intensity_stereo, bound==4 '01' subbands 8-31 in intensity_stereo, bound==8 '10' subbands 12-31 in intensity_stereo, bound==12 '11' subbands 16-31 in intensity_stereo, bound==16 12:13 Emphasis: '00' None '01' 50/15uS '10' reserved '11' CCITT J.17 14 CRC: '0' off '1' on 15 Copyright: '0' off '1' on 16 Generation: '0' copy '1' original ------------------------------------------------------------------------------- Name CX2341X_ENC_HALT_FW Enum 195/0xC3 Description The firmware is halted and no further API calls are serviced until the firmware is uploaded again. ------------------------------------------------------------------------------- Name CX2341X_ENC_GET_VERSION Enum 196/0xC4 Description Returns the version of the encoder firmware. Result[0] Version bitmask: Bits 0:15 build Bits 16:23 minor Bits 24:31 major ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_GOP_CLOSURE Enum 197/0xC5 Description Assigns the GOP open/close property. Param[0] 0=Open 1=Closed ------------------------------------------------------------------------------- Name CX2341X_ENC_GET_SEQ_END Enum 198/0xC6 Description Obtains the sequence end code of the encoder's buffer. When a capture is started a number of interrupts are still generated, the last of which will have Result[0] set to 1 and Result[1] will contain the size of the buffer. Result[0] State of the transfer (1 if last buffer) Result[1] If Result[0] is 1, this contains the size of the last buffer, undefined otherwise. ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_PGM_INDEX_INFO Enum 199/0xC7 Description Sets the Program Index Information. The information is stored as follows: struct info { u32 length; // Length of this frame u32 offset_low; // Offset in the file of the u32 offset_high; // start of this frame u32 mask1; // Bits 0-1 are the type mask: // 1=I, 2=P, 4=B u32 pts; // The PTS of the frame u32 mask2; // Bit 0 is bit 32 of the pts. }; u32 table_ptr; struct info index[400]; The table_ptr is the encoder memory address in the table were *new* entries will be written. Note that this is a ringbuffer, so the table_ptr will wraparound. Param[0] Picture Mask: 0=No index capture 1=I frames 3=I,P frames 7=I,P,B frames (Seems to be ignored, it always indexes I, P and B frames) Param[1] Elements requested (up to 400) Result[0] Offset in the encoder memory of the start of the table. Result[1] Number of allocated elements up to a maximum of Param[1] ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_VBI_CONFIG Enum 200/0xC8 Description Configure VBI settings Param[0] Bitmap: 0 Mode '0' Sliced, '1' Raw 1:3 Insertion: '000' insert in extension & user data '001' insert in private packets '010' separate stream and user data '111' separate stream and private data 8:15 Stream ID (normally 0xBD) Param[1] Frames per interrupt (max 8). Only valid in raw mode. Param[2] Total raw VBI frames. Only valid in raw mode. Param[3] Start codes Param[4] Stop codes Param[5] Lines per frame Param[6] Byte per line Result[0] Observed frames per interrupt in raw mode only. Rage 1 to Param[1] Result[1] Observed number of frames in raw mode. Range 1 to Param[2] Result[2] Memory offset to start or raw VBI data ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_DMA_BLOCK_SIZE Enum 201/0xC9 Description Set DMA transfer block size Param[0] DMA transfer block size in bytes or frames. When unit is bytes, supported block sizes are 2^7, 2^8 and 2^9 bytes. Param[1] Unit: 0=bytes, 1=frames ------------------------------------------------------------------------------- Name CX2341X_ENC_GET_PREV_DMA_INFO_MB_10 Enum 202/0xCA Description Returns information on the previous DMA transfer in conjunction with bit 27 of the interrupt mask. Uses mailbox 10. Result[0] Type of stream Result[1] Address Offset Result[2] Maximum size of transfer ------------------------------------------------------------------------------- Name CX2341X_ENC_GET_PREV_DMA_INFO_MB_9 Enum 203/0xCB Description Returns information on the previous DMA transfer in conjunction with bit 27 of the interrupt mask. Uses mailbox 9. Result[0] Status bits: Bit 0 set indicates transfer complete Bit 2 set indicates transfer error Bit 4 set indicates linked list error Result[1] DMA type Result[2] Presentation Time Stamp bits 0..31 Result[3] Presentation Time Stamp bit 32 ------------------------------------------------------------------------------- Name CX2341X_ENC_SCHED_DMA_TO_HOST Enum 204/0xCC Description Setup DMA to host operation Param[0] Memory address of link list Param[1] Length of link list (wtf: what units ???) Param[2] DMA type (0=MPEG) ------------------------------------------------------------------------------- Name CX2341X_ENC_INITIALIZE_INPUT Enum 205/0xCD Description Initializes the video input ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_FRAME_DROP_RATE Enum 208/0xD0 Description For each frame captured, skip specified number of frames. Param[0] Number of frames to skip ------------------------------------------------------------------------------- Name CX2341X_ENC_PAUSE_ENCODER Enum 210/0xD2 Description During a pause condition, all frames are dropped instead of being encoded. Param[0] 0=Pause encoding 1=Continue encoding ------------------------------------------------------------------------------- Name CX2341X_ENC_REFRESH_INPUT Enum 211/0xD3 Description Refreshes the video input ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_COPYRIGHT Enum 212/0xD4 Description Sets stream copyright property Param[0] 0=Stream is not copyrighted 1=Stream is copyrighted ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_EVENT_NOTIFICATION Enum 213/0xD5 Description Setup firmware to notify the host about a particular event. Host must unmask the interrupt bit. Param[0] Event (0=refresh encoder input) Param[1] Notification 0=disabled 1=enabled Param[2] Interrupt bit Param[3] Mailbox slot, -1 if no mailbox required. ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_NUM_VSYNC_LINES Enum 214/0xD6 Description Depending on the analog video decoder used, this assigns the number of lines for field 1 and 2. Param[0] Field 1 number of lines: 0x00EF for SAA7114 0x00F0 for SAA7115 0x0105 for Micronas Param[1] Field 2 number of lines: 0x00EF for SAA7114 0x00F0 for SAA7115 0x0106 for Micronas ------------------------------------------------------------------------------- Name CX2341X_ENC_SET_PLACEHOLDER Enum 215/0xD7 Description Provides a mechanism of inserting custom user data in the MPEG stream. Param[0] 0=extension & user data 1=private packet with stream ID 0xBD Param[1] Rate at which to insert data, in units of frames (for private packet) or GOPs (for ext. & user data) Param[2] Number of data DWORDs (below) to insert Param[3] Custom data 0 Param[4] Custom data 1 Param[5] Custom data 2 Param[6] Custom data 3 Param[7] Custom data 4 Param[8] Custom data 5 Param[9] Custom data 6 Param[10] Custom data 7 Param[11] Custom data 8 ------------------------------------------------------------------------------- Name CX2341X_ENC_MUTE_VIDEO Enum 217/0xD9 Description Video muting Param[0] Bit usage: 0 '0'=video not muted '1'=video muted, creates frames with the YUV color defined below 1:7 Unused 8:15 V chrominance information 16:23 U chrominance information 24:31 Y luminance information ------------------------------------------------------------------------------- Name CX2341X_ENC_MUTE_AUDIO Enum 218/0xDA Description Audio muting Param[0] 0=audio not muted 1=audio muted (produces silent mpeg audio stream) ------------------------------------------------------------------------------- Name CX2341X_ENC_UNKNOWN Enum 219/0xDB Description Unknown API, it's used by Hauppauge though. Param[0] 0 This is the value Hauppauge uses, Unknown what it means. ------------------------------------------------------------------------------- Name CX2341X_ENC_MISC Enum 220/0xDC Description Miscellaneous actions. Not known for 100% what it does. It's really a sort of ioctl call. The first parameter is a command number, the second the value. Param[0] Command number: 1=set initial SCR value when starting encoding. 2=set quality mode (apparently some test setting). 3=setup advanced VIM protection handling (supposedly only for the cx23416 for raw YUV). Actually it looks like this should be 0 for saa7114/5 based card and 1 for cx25840 based cards. 4=generate artificial PTS timestamps 5=USB flush mode 6=something to do with the quantization matrix 7=set navigation pack insertion for DVD 8=enable scene change detection (seems to be a failure) 9=set history parameters of the video input module 10=set input field order of VIM 11=set quantization matrix 12=reset audio interface 13=set audio volume delay 14=set audio delay Param[1] Command value.