dav1d is an AV1 video codec implementation created by the kind folks at VideoLAN and is widely used.
This Nim wrapper puts a low-cost memory safe high level on top of it. If the low-level API is required, applications can include dav1d/wrapper directly.
Types
InitError = object of ValueError
- Error is raised if something about initializing the decoder doesn't work out
DecodeError = object of ValueError
- Error is raised if there is a permanent error sending data to the decoder
BufferError = object of ValueError
- Error is raised if the data send failed because decoded data need be retrieved first, or if data retrieve failed because insufficient data was send. This is usually caught and decoding resumed when the condition has been resolved.
DecoderObj = object settings*: Settings context*: ptr Context
- Holds the initialization data for a Dav1d decoder
Decoder = ref DecoderObj
- which in turn frees the wrapped library's untraced heap memory.
PictureObj = object raw*: ptr cPicture when compileOption("threads"): creatingThread*: int
- A container object for one frame of decoded video data
Picture = ref PictureObj
- A memory safe reference to one frame of decoded video data
Data = ref cData
- A memory safe reference to encoded video data
Procs
proc flush(decoder: Decoder) {...}{.raises: [], tags: [].}
- Reset the decoder. Do this before a seek
proc newDecoder(): Decoder {...}{.raises: [InitError], tags: [].}
- Initialize a decoder
proc newData(encoded: openArray[byte]): Data {...}{.raises: [DecodeError], tags: [].}
- Create a new data object from an encoded data chunk that can be sent to the decoder.
proc send(decoder: Decoder; data: Data) {...}{. raises: [BufferError, DecodeError, ValueError], tags: [].}
- Actually send the data to the decoder. It will be available to retrieve using the getPicture object If a BufferError is raised, then no more data can be queued- getPicture needs to be called first. This error should be caught, and responeded to. If a DecodeError is raised, then something actually is wrong with the encoded data
proc getPicture(decoder: Decoder): Picture {...}{. raises: [BufferError, DecodeError, ValueError], tags: [].}
- Retrieve one frame of decoded video data. If a BufferError is raised, not enough data is available- call send first and try again. If a DecodeError is raised, something is actually wrong with the decoding process.
Templates
template newData(encoded: ptr UncheckedArray[byte]; len: int): Data
- Create a new data object from an unchecked array and a length instead of an OpenArray This can also be used to send a pointer and a length, by casting it to the UncheckedArray[byte] type
template send(decoder: Decoder; encoded: openArray[byte])
- Convenience function to send array data to the encoded without explicitly creating a data object. toOpenArray can be used to send further types of data
template send(decoder: Decoder; encoded: ptr UncheckedArray[byte]; len: int)
- Convenience function to send array-and-length data to dav1d