creek_core/read/
decoder.rs

1use std::path::PathBuf;
2use std::{error::Error, fmt::Debug};
3
4use super::DataBlock;
5use crate::FileInfo;
6
7/// A type that decodes a file in a read stream.
8pub trait Decoder: Sized + 'static {
9    /// The data type of a single sample. (i.e. `f32`)
10    type T: Copy + Clone + Default + Send;
11
12    /// Any additional options for opening a file with this decoder.
13    type AdditionalOpts: Send + Default + Debug;
14
15    /// Any additional information on the file.
16    type FileParams: Clone + Send;
17
18    /// The error type while opening the file.
19    type OpenError: Error + Send;
20
21    /// The error type when a fatal error occurs.
22    type FatalError: Error + Send;
23
24    /// The default number of frames in a prefetch block.
25    const DEFAULT_BLOCK_SIZE: usize;
26
27    /// The default number of prefetch blocks in a cache block. This will cause a cache to be
28    /// used whenever the stream is seeked to a frame in the range:
29    ///
30    /// `[cache_start, cache_start + (num_cache_blocks * block_size))`
31    ///
32    /// If this is 0, then the cache is only used when seeked to exactly `cache_start`.
33    const DEFAULT_NUM_CACHE_BLOCKS: usize;
34
35    /// The number of prefetch blocks to store ahead of the cache block. This must be
36    /// sufficiently large to ensure enough to time to fill the buffer in the worst
37    /// case latency scenario.
38    const DEFAULT_NUM_LOOK_AHEAD_BLOCKS: usize;
39
40    /// Open the file and start reading from `start_frame`.
41    ///
42    /// Please note this algorithm depends on knowing the exact number of frames in a file.
43    /// Do **not** return an approximate length in the returned `FileInfo`.
44    fn new(
45        file: PathBuf,
46        start_frame: usize,
47        block_size: usize,
48        additional_opts: Self::AdditionalOpts,
49    ) -> Result<(Self, FileInfo<Self::FileParams>), Self::OpenError>;
50
51    /// Seek to a frame in the file. If a frame lies outside of the end of the file,
52    /// set the read position the end of the file instead of returning an error.
53    fn seek(&mut self, frame: usize) -> Result<(), Self::FatalError>;
54
55    /// Decode data into the `data_block` starting from your current internal read position.
56    /// This is streaming, meaning the next call to `decode()` should pick up where the
57    /// previous left off.
58    ///
59    /// Fill each channel in the data block with `block_size` number of frames (you should
60    /// have gotten this value from `Decoder::new()`). If there isn't enough data left
61    /// because the end of the file has been reached, then only fill up how ever many frames
62    /// are left. If the end of the file has already been reached since the last call to
63    /// `decode()`, then do nothing.
64    ///
65    /// Each channel Vec in `data_block` will have a length of zero.
66    fn decode(&mut self, data_block: &mut DataBlock<Self::T>) -> Result<(), Self::FatalError>;
67
68    /// Return the current read position.
69    fn current_frame(&self) -> usize;
70}
creek_core/read/decoder.rs

creek_core/read/
decoder.rs
