nom_exif/
parser.rs

1use std::{
2    cmp::{max, min},
3    fmt::{Debug, Display},
4    fs::File,
5    io::{self, Read, Seek},
6    marker::PhantomData,
7    net::TcpStream,
8    ops::Range,
9    path::Path,
10};
11
12use crate::{
13    buffer::Buffers,
14    error::{ParsedError, ParsingError, ParsingErrorState},
15    exif::{parse_exif_iter, TiffHeader},
16    file::Mime,
17    partial_vec::PartialVec,
18    skip::Skip,
19    video::parse_track_info,
20    ExifIter, Seekable, TrackInfo, Unseekable,
21};
22
23/// `MediaSource` represents a media data source that can be parsed by
24/// [`MediaParser`].
25///
26/// - Use `MediaSource::file_path(path)` or `MediaSource::file(file)` to create
27///   a MediaSource from a file
28///
29/// - Use `MediaSource::tcp_stream(stream)` to create a MediaSource from a `TcpStream`
30/// - In other cases:
31///
32///   - Use `MediaSource::seekable(reader)` to create a MediaSource from a `Read + Seek`
33///   
34///   - Use `MediaSource::unseekable(reader)` to create a MediaSource from a
35///     reader that only impl `Read`
36///   
37/// `seekable` is preferred to `unseekable`, since the former is more efficient
38/// when the parser needs to skip a large number of bytes.
39///
40/// Passing in a `BufRead` should be avoided because [`MediaParser`] comes with
41/// its own buffer management and the buffers can be shared between multiple
42/// parsing tasks, thus avoiding frequent memory allocations.
43pub struct MediaSource<R, S = Seekable> {
44    pub(crate) reader: R,
45    pub(crate) buf: Vec<u8>,
46    pub(crate) mime: Mime,
47    phantom: PhantomData<S>,
48}
49
50impl<R, S: Skip<R>> Debug for MediaSource<R, S> {
51    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
52        f.debug_struct("MediaSource")
53            // .field("reader", &self.reader)
54            .field("mime", &self.mime)
55            .field("seekable", &S::debug())
56            .finish_non_exhaustive()
57    }
58}
59
60// Should be enough for parsing header
61const HEADER_PARSE_BUF_SIZE: usize = 128;
62
63impl<R: Read, S: Skip<R>> MediaSource<R, S> {
64    #[tracing::instrument(skip(reader))]
65    fn build(mut reader: R) -> crate::Result<Self> {
66        // TODO: reuse MediaParser to parse header
67        let mut buf = Vec::with_capacity(HEADER_PARSE_BUF_SIZE);
68        reader
69            .by_ref()
70            .take(HEADER_PARSE_BUF_SIZE as u64)
71            .read_to_end(&mut buf)?;
72        let mime: Mime = buf.as_slice().try_into()?;
73        tracing::debug!(?mime);
74        Ok(Self {
75            reader,
76            buf,
77            mime,
78            phantom: PhantomData,
79        })
80    }
81
82    pub fn has_track(&self) -> bool {
83        match self.mime {
84            Mime::Image(_) => false,
85            Mime::Video(_) => true,
86        }
87    }
88
89    pub fn has_exif(&self) -> bool {
90        match self.mime {
91            Mime::Image(_) => true,
92            Mime::Video(_) => false,
93        }
94    }
95}
96
97impl<R: Read + Seek> MediaSource<R, Seekable> {
98    pub fn seekable(reader: R) -> crate::Result<Self> {
99        Self::build(reader)
100    }
101}
102
103impl<R: Read> MediaSource<R, Unseekable> {
104    pub fn unseekable(reader: R) -> crate::Result<Self> {
105        Self::build(reader)
106    }
107}
108
109impl MediaSource<File, Seekable> {
110    pub fn file_path<P: AsRef<Path>>(path: P) -> crate::Result<Self> {
111        Self::seekable(File::open(path)?)
112    }
113
114    pub fn file(file: File) -> crate::Result<Self> {
115        Self::seekable(file)
116    }
117}
118
119impl MediaSource<TcpStream, Unseekable> {
120    pub fn tcp_stream(stream: TcpStream) -> crate::Result<Self> {
121        Self::unseekable(stream)
122    }
123}
124
125// Keep align with 4K
126pub(crate) const INIT_BUF_SIZE: usize = 4096;
127pub(crate) const MIN_GROW_SIZE: usize = 4096;
128// Max size of APP1 is 0xFFFF
129pub(crate) const MAX_GROW_SIZE: usize = 63 * 1024;
130// Set a reasonable upper limit for single buffer allocation.
131pub(crate) const MAX_ALLOC_SIZE: usize = 100 * 1024 * 1024;
132
133pub(crate) trait Buf {
134    fn buffer(&self) -> &[u8];
135    fn clear(&mut self);
136
137    fn set_position(&mut self, pos: usize);
138    #[allow(unused)]
139    fn position(&self) -> usize;
140}
141
142#[derive(Debug, Clone)]
143pub(crate) enum ParsingState {
144    TiffHeader(TiffHeader),
145    HeifExifSize(usize),
146}
147
148impl Display for ParsingState {
149    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
150        match self {
151            ParsingState::TiffHeader(h) => Display::fmt(&format!("ParsingState: {h:?})"), f),
152            ParsingState::HeifExifSize(n) => Display::fmt(&format!("ParsingState: {n}"), f),
153        }
154    }
155}
156
157pub(crate) trait BufParser: Buf + Debug {
158    fn fill_buf<R: Read>(&mut self, reader: &mut R, size: usize) -> io::Result<usize>;
159    fn load_and_parse<R: Read, S: Skip<R>, P, O>(
160        &mut self,
161        reader: &mut R,
162        mut parse: P,
163    ) -> Result<O, ParsedError>
164    where
165        P: FnMut(&[u8], Option<ParsingState>) -> Result<O, ParsingErrorState>,
166    {
167        self.load_and_parse_with_offset::<R, S, _, _>(
168            reader,
169            |data, _, state| parse(data, state),
170            0,
171        )
172    }
173
174    #[tracing::instrument(skip_all)]
175    fn load_and_parse_with_offset<R: Read, S: Skip<R>, P, O>(
176        &mut self,
177        reader: &mut R,
178        mut parse: P,
179        offset: usize,
180    ) -> Result<O, ParsedError>
181    where
182        P: FnMut(&[u8], usize, Option<ParsingState>) -> Result<O, ParsingErrorState>,
183    {
184        if offset >= self.buffer().len() {
185            self.fill_buf(reader, MIN_GROW_SIZE)?;
186        }
187
188        let mut parsing_state: Option<ParsingState> = None;
189        loop {
190            let res = parse(self.buffer(), offset, parsing_state.take());
191            match res {
192                Ok(o) => return Ok(o),
193                Err(es) => {
194                    tracing::debug!(?es);
195                    parsing_state = es.state;
196
197                    match es.err {
198                        ParsingError::ClearAndSkip(n) => {
199                            self.clear_and_skip::<R, S>(reader, n)?;
200                        }
201                        ParsingError::Need(i) => {
202                            tracing::debug!(need = i, "need more bytes");
203                            let to_read = max(i, MIN_GROW_SIZE);
204                            let to_read = min(to_read, MAX_GROW_SIZE);
205
206                            let n = self.fill_buf(reader, to_read)?;
207                            if n == 0 {
208                                return Err(ParsedError::NoEnoughBytes);
209                            }
210                            tracing::debug!(n, "actual read");
211                        }
212                        ParsingError::Failed(s) => return Err(ParsedError::Failed(s)),
213                    }
214                }
215            }
216        }
217    }
218
219    #[tracing::instrument(skip(reader))]
220    fn clear_and_skip<R: Read, S: Skip<R>>(
221        &mut self,
222        reader: &mut R,
223        n: usize,
224    ) -> Result<(), ParsedError> {
225        tracing::debug!("ClearAndSkip");
226        if n <= self.buffer().len() {
227            tracing::debug!(n, "skip by set_position");
228            self.set_position(n);
229            return Ok(());
230        }
231
232        let skip_n = n - self.buffer().len();
233        tracing::debug!(skip_n, "clear and skip bytes");
234        self.clear();
235
236        let done = S::skip_by_seek(
237            reader,
238            skip_n
239                .try_into()
240                .map_err(|_| ParsedError::Failed("skip too many bytes".into()))?,
241        )?;
242        if !done {
243            tracing::debug!(skip_n, "skip by using our buffer");
244            let mut skipped = 0;
245            while skipped < skip_n {
246                let mut to_skip = skip_n - skipped;
247                to_skip = min(to_skip, MAX_ALLOC_SIZE);
248                let n = self.fill_buf(reader, to_skip)?;
249                skipped += n;
250                if skipped <= skip_n {
251                    self.clear();
252                } else {
253                    let remain = skipped - skip_n;
254                    self.set_position(self.buffer().len() - remain);
255                    break;
256                }
257            }
258        } else {
259            tracing::debug!(skip_n, "skip with seek");
260        }
261
262        if self.buffer().is_empty() {
263            self.fill_buf(reader, MIN_GROW_SIZE)?;
264        }
265        Ok(())
266    }
267}
268
269impl BufParser for MediaParser {
270    #[tracing::instrument(skip(self, reader))]
271    fn fill_buf<R: Read>(&mut self, reader: &mut R, size: usize) -> io::Result<usize> {
272        if size > MAX_ALLOC_SIZE {
273            tracing::error!(?size, "the requested buffer size is too big");
274            return Err(io::ErrorKind::Unsupported.into());
275        }
276        self.buf_mut().reserve_exact(size);
277
278        let n = reader.take(size as u64).read_to_end(self.buf_mut())?;
279        if n == 0 {
280            return Err(std::io::ErrorKind::UnexpectedEof.into());
281        }
282
283        Ok(n)
284    }
285}
286
287impl Buf for MediaParser {
288    fn buffer(&self) -> &[u8] {
289        &self.buf()[self.position..]
290    }
291
292    fn clear(&mut self) {
293        self.buf_mut().clear();
294    }
295
296    fn set_position(&mut self, pos: usize) {
297        self.position = pos;
298    }
299
300    fn position(&self) -> usize {
301        self.position
302    }
303}
304
305pub trait ParseOutput<R, S>: Sized {
306    fn parse(parser: &mut MediaParser, ms: MediaSource<R, S>) -> crate::Result<Self>;
307}
308
309impl<R: Read, S: Skip<R>> ParseOutput<R, S> for ExifIter {
310    fn parse(parser: &mut MediaParser, mut ms: MediaSource<R, S>) -> crate::Result<Self> {
311        if !ms.has_exif() {
312            return Err(crate::Error::ParseFailed("no Exif data here".into()));
313        }
314        parse_exif_iter::<R, S>(parser, ms.mime.unwrap_image(), &mut ms.reader)
315    }
316}
317
318impl<R: Read, S: Skip<R>> ParseOutput<R, S> for TrackInfo {
319    fn parse(parser: &mut MediaParser, mut ms: MediaSource<R, S>) -> crate::Result<Self> {
320        if !ms.has_track() {
321            return Err(crate::Error::ParseFailed("no track info here".into()));
322        }
323        let out = parser.load_and_parse::<R, S, _, _>(ms.reader.by_ref(), |data, _| {
324            parse_track_info(data, ms.mime.unwrap_video())
325                .map_err(|e| ParsingErrorState::new(e, None))
326        })?;
327        Ok(out)
328    }
329}
330
331/// A `MediaParser`/`AsyncMediaParser` can parse media info from a
332/// [`MediaSource`].
333///
334/// `MediaParser`/`AsyncMediaParser` manages inner parse buffers that can be
335/// shared between multiple parsing tasks, thus avoiding frequent memory
336/// allocations.
337///
338/// Therefore:
339///
340/// - Try to reuse a `MediaParser`/`AsyncMediaParser` instead of creating a new
341///   one every time you need it.
342///   
343/// - `MediaSource` should be created directly from `Read`, not from `BufRead`.
344///
345/// ## Example
346///
347/// ```rust
348/// use nom_exif::*;
349/// use chrono::DateTime;
350///
351/// let mut parser = MediaParser::new();
352///
353/// // ------------------- Parse Exif Info
354/// let ms = MediaSource::file_path("./testdata/exif.heic").unwrap();
355/// assert!(ms.has_exif());
356/// let mut iter: ExifIter = parser.parse(ms).unwrap();
357///
358/// let entry = iter.next().unwrap();
359/// assert_eq!(entry.tag().unwrap(), ExifTag::Make);
360/// assert_eq!(entry.get_value().unwrap().as_str().unwrap(), "Apple");
361///
362/// // Convert `ExifIter` into an `Exif`. Clone it before converting, so that
363/// // we can start the iteration from the beginning.
364/// let exif: Exif = iter.clone().into();
365/// assert_eq!(exif.get(ExifTag::Make).unwrap().as_str().unwrap(), "Apple");
366///
367/// // ------------------- Parse Track Info
368/// let ms = MediaSource::file_path("./testdata/meta.mov").unwrap();
369/// assert!(ms.has_track());
370/// let info: TrackInfo = parser.parse(ms).unwrap();
371///
372/// assert_eq!(info.get(TrackInfoTag::Make), Some(&"Apple".into()));
373/// assert_eq!(info.get(TrackInfoTag::Model), Some(&"iPhone X".into()));
374/// assert_eq!(info.get(TrackInfoTag::GpsIso6709), Some(&"+27.1281+100.2508+000.000/".into()));
375/// assert_eq!(info.get_gps_info().unwrap().latitude_ref, 'N');
376/// assert_eq!(
377///     info.get_gps_info().unwrap().latitude,
378///     [(27, 1), (7, 1), (68, 100)].into(),
379/// );
380/// ```
381pub struct MediaParser {
382    bb: Buffers,
383    buf: Option<Vec<u8>>,
384    position: usize,
385}
386
387impl Debug for MediaParser {
388    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
389        f.debug_struct("MediaParser")
390            .field("buffers", &self.bb)
391            .field("buf len", &self.buf.as_ref().map(|x| x.len()))
392            .field("position", &self.position)
393            .finish_non_exhaustive()
394    }
395}
396
397impl Default for MediaParser {
398    fn default() -> Self {
399        Self {
400            bb: Buffers::new(),
401            buf: None,
402            position: 0,
403        }
404    }
405}
406
407pub(crate) trait ShareBuf {
408    fn share_buf(&mut self, range: Range<usize>) -> PartialVec;
409}
410
411impl ShareBuf for MediaParser {
412    fn share_buf(&mut self, mut range: Range<usize>) -> PartialVec {
413        let buf = self.buf.take().unwrap();
414        let vec = self.bb.release_to_share(buf);
415        range.start += self.position;
416        range.end += self.position;
417        PartialVec::new(vec, range)
418    }
419}
420
421impl MediaParser {
422    pub fn new() -> Self {
423        Self::default()
424    }
425
426    /// `MediaParser`/`AsyncMediaParser` comes with its own buffer management,
427    /// so that buffers can be reused during multiple parsing processes to
428    /// avoid frequent memory allocations. Therefore, try to reuse a
429    /// `MediaParser` instead of creating a new one every time you need it.
430    ///     
431    /// **Note**:
432    ///
433    /// - For [`ExifIter`] as parse output, Please avoid holding the `ExifIter`
434    ///   object all the time and drop it immediately after use. Otherwise, the
435    ///   parsing buffer referenced by the `ExifIter` object will not be reused
436    ///   by [`MediaParser`], resulting in repeated memory allocation in the
437    ///   subsequent parsing process.
438    ///
439    ///   If you really need to retain some data, please take out the required
440    ///   Entry values and save them, or convert the `ExifIter` into an
441    ///   [`crate::Exif`] object to retain all Entry values.
442    ///
443    /// - For [`TrackInfo`] as parse output, you don't need to worry about
444    ///   this, because `TrackInfo` dosn't reference the parsing buffer.
445    pub fn parse<R: Read, S, O: ParseOutput<R, S>>(
446        &mut self,
447        mut ms: MediaSource<R, S>,
448    ) -> crate::Result<O> {
449        self.reset();
450        self.acquire_buf();
451
452        self.buf_mut().append(&mut ms.buf);
453        let res = self.do_parse(ms);
454
455        self.reset();
456        res
457    }
458
459    fn do_parse<R: Read, S, O: ParseOutput<R, S>>(
460        &mut self,
461        mut ms: MediaSource<R, S>,
462    ) -> Result<O, crate::Error> {
463        self.fill_buf(&mut ms.reader, INIT_BUF_SIZE)?;
464        let res = ParseOutput::parse(self, ms)?;
465        Ok(res)
466    }
467
468    fn reset(&mut self) {
469        // Ensure buf has been released
470        if let Some(buf) = self.buf.take() {
471            self.bb.release(buf);
472        }
473
474        // Reset position
475        self.set_position(0);
476    }
477
478    pub(crate) fn buf(&self) -> &Vec<u8> {
479        match self.buf.as_ref() {
480            Some(b) => b,
481            None => panic!("no buf here"),
482        }
483    }
484
485    fn buf_mut(&mut self) -> &mut Vec<u8> {
486        match self.buf.as_mut() {
487            Some(b) => b,
488            None => panic!("no buf here"),
489        }
490    }
491
492    fn acquire_buf(&mut self) {
493        assert!(self.buf.is_none());
494        self.buf = Some(self.bb.acquire());
495    }
496}
497
498#[cfg(test)]
499mod tests {
500    use std::sync::{LazyLock, Mutex, MutexGuard};
501
502    use super::*;
503    use test_case::case;
504
505    enum TrackExif {
506        Track,
507        Exif,
508        NoData,
509        Invalid,
510    }
511    use TrackExif::*;
512
513    static PARSER: LazyLock<Mutex<MediaParser>> = LazyLock::new(|| Mutex::new(MediaParser::new()));
514    fn parser() -> MutexGuard<'static, MediaParser> {
515        PARSER.lock().unwrap()
516    }
517
518    #[case("3gp_640x360.3gp", Track)]
519    #[case("broken.jpg", Exif)]
520    #[case("compatible-brands-fail.heic", Invalid)]
521    #[case("compatible-brands-fail.mov", Invalid)]
522    #[case("compatible-brands.heic", NoData)]
523    #[case("compatible-brands.mov", NoData)]
524    #[case("embedded-in-heic.mov", Track)]
525    #[case("exif.heic", Exif)]
526    #[case("exif.jpg", Exif)]
527    #[case("exif-no-tz.jpg", Exif)]
528    #[case("fujifilm_x_t1_01.raf.meta", Exif)]
529    #[case("meta.mov", Track)]
530    #[case("meta.mp4", Track)]
531    #[case("mka.mka", Track)]
532    #[case("mkv_640x360.mkv", Track)]
533    #[case("exif-one-entry.heic", Exif)]
534    #[case("no-exif.jpg", NoData)]
535    #[case("tif.tif", Exif)]
536    #[case("ramdisk.img", Invalid)]
537    #[case("webm_480.webm", Track)]
538    fn parse_media(path: &str, te: TrackExif) {
539        let mut parser = parser();
540        let ms = MediaSource::file_path(Path::new("testdata").join(path));
541        match te {
542            Track => {
543                let ms = ms.unwrap();
544                // println!("path: {path} mime: {:?}", ms.mime);
545                assert!(ms.has_track());
546                let _: TrackInfo = parser.parse(ms).unwrap();
547            }
548            Exif => {
549                let ms = ms.unwrap();
550                // println!("path: {path} mime: {:?}", ms.mime);
551                assert!(ms.has_exif());
552                let mut it: ExifIter = parser.parse(ms).unwrap();
553                let _ = it.parse_gps_info();
554
555                if path.contains("one-entry") {
556                    assert!(it.next().is_some());
557                    assert!(it.next().is_none());
558
559                    let exif: crate::Exif = it.clone_and_rewind().into();
560                    assert!(exif.get(ExifTag::Orientation).is_some());
561                } else {
562                    let _: crate::Exif = it.clone_and_rewind().into();
563                }
564            }
565            NoData => {
566                let ms = ms.unwrap();
567                // println!("path: {path} mime: {:?}", ms.mime);
568                if ms.has_exif() {
569                    let res: Result<ExifIter, _> = parser.parse(ms);
570                    res.unwrap_err();
571                } else if ms.has_track() {
572                    let res: Result<TrackInfo, _> = parser.parse(ms);
573                    res.unwrap_err();
574                }
575            }
576            Invalid => {
577                ms.unwrap_err();
578            }
579        }
580    }
581
582    use crate::testkit::open_sample;
583    use crate::{EntryValue, ExifTag, TrackInfoTag};
584    use chrono::DateTime;
585    use test_case::test_case;
586
587    use crate::video::TrackInfoTag::*;
588
589    #[test_case("mkv_640x360.mkv", ImageWidth, 640_u32.into())]
590    #[test_case("mkv_640x360.mkv", ImageHeight, 360_u32.into())]
591    #[test_case("mkv_640x360.mkv", DurationMs, 13346_u64.into())]
592    #[test_case("mkv_640x360.mkv", CreateDate, DateTime::parse_from_str("2008-08-08T08:08:08Z", "%+").unwrap().into())]
593    #[test_case("meta.mov", Make, "Apple".into())]
594    #[test_case("meta.mov", Model, "iPhone X".into())]
595    #[test_case("meta.mov", GpsIso6709, "+27.1281+100.2508+000.000/".into())]
596    #[test_case("meta.mp4", ImageWidth, 1920_u32.into())]
597    #[test_case("meta.mp4", ImageHeight, 1080_u32.into())]
598    #[test_case("meta.mp4", DurationMs, 1063_u64.into())]
599    #[test_case("meta.mp4", GpsIso6709, "+27.2939+112.6932/".into())]
600    #[test_case("meta.mp4", CreateDate, DateTime::parse_from_str("2024-02-03T07:05:38Z", "%+").unwrap().into())]
601    #[test_case("udta.auth.mp4", Author, "ReplayKitRecording".into(); "udta author")]
602    #[test_case("auth.mov", Author, "ReplayKitRecording".into(); "mov author")]
603    fn parse_track_info(path: &str, tag: TrackInfoTag, v: EntryValue) {
604        let mut parser = parser();
605
606        let mf = MediaSource::file(open_sample(path).unwrap()).unwrap();
607        let info: TrackInfo = parser.parse(mf).unwrap();
608        assert_eq!(info.get(tag).unwrap(), &v);
609
610        let mf = MediaSource::unseekable(open_sample(path).unwrap()).unwrap();
611        let info: TrackInfo = parser.parse(mf).unwrap();
612        assert_eq!(info.get(tag).unwrap(), &v);
613    }
614
615    #[test_case("crash_moov-trak")]
616    #[test_case("crash_skip_large")]
617    #[test_case("crash_add_large")]
618    fn parse_track_crash(path: &str) {
619        let mut parser = parser();
620
621        let mf = MediaSource::file(open_sample(path).unwrap()).unwrap();
622        let _: TrackInfo = parser.parse(mf).unwrap_or_default();
623
624        let mf = MediaSource::unseekable(open_sample(path).unwrap()).unwrap();
625        let _: TrackInfo = parser.parse(mf).unwrap_or_default();
626    }
627}
nom_exif/parser.rs

nom_exif/
parser.rs
