Mercurial > libavformat.hg
comparison avformat.h @ 1840:daaa79ca14f0 libavformat
Move the libavformat public API comments to avformat.h. The comments are
unmodified.
author | takis |
---|---|
date | Sat, 03 Mar 2007 12:23:20 +0000 |
parents | 62792a60f740 |
children | 2c91663b3bc6 |
comparison
equal
deleted
inserted
replaced
1839:cd4c59c788fc | 1840:daaa79ca14f0 |
---|---|
52 int64_t pos; ///< byte position in stream, -1 if unknown | 52 int64_t pos; ///< byte position in stream, -1 if unknown |
53 } AVPacket; | 53 } AVPacket; |
54 #define PKT_FLAG_KEY 0x0001 | 54 #define PKT_FLAG_KEY 0x0001 |
55 | 55 |
56 void av_destruct_packet_nofree(AVPacket *pkt); | 56 void av_destruct_packet_nofree(AVPacket *pkt); |
57 | |
58 /** | |
59 * Default packet destructor. | |
60 */ | |
57 void av_destruct_packet(AVPacket *pkt); | 61 void av_destruct_packet(AVPacket *pkt); |
58 | 62 |
59 /* initialize optional fields of a packet */ | 63 /* initialize optional fields of a packet */ |
60 static inline void av_init_packet(AVPacket *pkt) | 64 static inline void av_init_packet(AVPacket *pkt) |
61 { | 65 { |
66 pkt->flags = 0; | 70 pkt->flags = 0; |
67 pkt->stream_index = 0; | 71 pkt->stream_index = 0; |
68 pkt->destruct= av_destruct_packet_nofree; | 72 pkt->destruct= av_destruct_packet_nofree; |
69 } | 73 } |
70 | 74 |
75 /** | |
76 * Allocate the payload of a packet and intialized its fields to default values. | |
77 * | |
78 * @param pkt packet | |
79 * @param size wanted payload size | |
80 * @return 0 if OK. AVERROR_xxx otherwise. | |
81 */ | |
71 int av_new_packet(AVPacket *pkt, int size); | 82 int av_new_packet(AVPacket *pkt, int size); |
83 | |
84 /** | |
85 * Allocate and read the payload of a packet and intialized its fields to default values. | |
86 * | |
87 * @param pkt packet | |
88 * @param size wanted payload size | |
89 * @return >0 (read size) if OK. AVERROR_xxx otherwise. | |
90 */ | |
72 int av_get_packet(ByteIOContext *s, AVPacket *pkt, int size); | 91 int av_get_packet(ByteIOContext *s, AVPacket *pkt, int size); |
92 | |
93 /* This is a hack - the packet memory allocation stuff is broken. The | |
94 packet is allocated if it was not really allocated */ | |
73 int av_dup_packet(AVPacket *pkt); | 95 int av_dup_packet(AVPacket *pkt); |
74 | 96 |
75 /** | 97 /** |
76 * Free a packet | 98 * Free a packet |
77 * | 99 * |
408 void av_register_output_format(AVOutputFormat *format); | 430 void av_register_output_format(AVOutputFormat *format); |
409 AVOutputFormat *guess_stream_format(const char *short_name, | 431 AVOutputFormat *guess_stream_format(const char *short_name, |
410 const char *filename, const char *mime_type); | 432 const char *filename, const char *mime_type); |
411 AVOutputFormat *guess_format(const char *short_name, | 433 AVOutputFormat *guess_format(const char *short_name, |
412 const char *filename, const char *mime_type); | 434 const char *filename, const char *mime_type); |
435 | |
436 /** | |
437 * Guesses the codec id based upon muxer and filename. | |
438 */ | |
413 enum CodecID av_guess_codec(AVOutputFormat *fmt, const char *short_name, | 439 enum CodecID av_guess_codec(AVOutputFormat *fmt, const char *short_name, |
414 const char *filename, const char *mime_type, enum CodecType type); | 440 const char *filename, const char *mime_type, enum CodecType type); |
415 | 441 |
442 /** | |
443 * Print nice hexa dump of a buffer | |
444 * @param f stream for output | |
445 * @param buf buffer | |
446 * @param size buffer size | |
447 */ | |
416 void av_hex_dump(FILE *f, uint8_t *buf, int size); | 448 void av_hex_dump(FILE *f, uint8_t *buf, int size); |
449 | |
450 /** | |
451 * Print on 'f' a nice dump of a packet | |
452 * @param f stream for output | |
453 * @param pkt packet to dump | |
454 * @param dump_payload true if the payload must be displayed too | |
455 */ | |
417 void av_pkt_dump(FILE *f, AVPacket *pkt, int dump_payload); | 456 void av_pkt_dump(FILE *f, AVPacket *pkt, int dump_payload); |
418 | 457 |
419 void av_register_all(void); | 458 void av_register_all(void); |
420 | 459 |
421 /* codec tag <-> codec id */ | 460 /* codec tag <-> codec id */ |
422 enum CodecID av_codec_get_id(const struct AVCodecTag **tags, unsigned int tag); | 461 enum CodecID av_codec_get_id(const struct AVCodecTag **tags, unsigned int tag); |
423 unsigned int av_codec_get_tag(const struct AVCodecTag **tags, enum CodecID id); | 462 unsigned int av_codec_get_tag(const struct AVCodecTag **tags, enum CodecID id); |
424 | 463 |
425 /* media file input */ | 464 /* media file input */ |
465 | |
466 /** | |
467 * finds AVInputFormat based on input format's short name. | |
468 */ | |
426 AVInputFormat *av_find_input_format(const char *short_name); | 469 AVInputFormat *av_find_input_format(const char *short_name); |
470 | |
471 /** | |
472 * Guess file format. | |
473 * | |
474 * @param is_opened whether the file is already opened, determines whether | |
475 * demuxers with or without AVFMT_NOFILE are probed | |
476 */ | |
427 AVInputFormat *av_probe_input_format(AVProbeData *pd, int is_opened); | 477 AVInputFormat *av_probe_input_format(AVProbeData *pd, int is_opened); |
478 | |
479 /** | |
480 * Allocates all the structures needed to read an input stream. | |
481 * This does not open the needed codecs for decoding the stream[s]. | |
482 */ | |
428 int av_open_input_stream(AVFormatContext **ic_ptr, | 483 int av_open_input_stream(AVFormatContext **ic_ptr, |
429 ByteIOContext *pb, const char *filename, | 484 ByteIOContext *pb, const char *filename, |
430 AVInputFormat *fmt, AVFormatParameters *ap); | 485 AVInputFormat *fmt, AVFormatParameters *ap); |
486 | |
487 /** | |
488 * Open a media file as input. The codec are not opened. Only the file | |
489 * header (if present) is read. | |
490 * | |
491 * @param ic_ptr the opened media file handle is put here | |
492 * @param filename filename to open. | |
493 * @param fmt if non NULL, force the file format to use | |
494 * @param buf_size optional buffer size (zero if default is OK) | |
495 * @param ap additionnal parameters needed when opening the file (NULL if default) | |
496 * @return 0 if OK. AVERROR_xxx otherwise. | |
497 */ | |
431 int av_open_input_file(AVFormatContext **ic_ptr, const char *filename, | 498 int av_open_input_file(AVFormatContext **ic_ptr, const char *filename, |
432 AVInputFormat *fmt, | 499 AVInputFormat *fmt, |
433 int buf_size, | 500 int buf_size, |
434 AVFormatParameters *ap); | 501 AVFormatParameters *ap); |
435 /* no av_open for output, so applications will need this: */ | 502 /* no av_open for output, so applications will need this: */ |
436 AVFormatContext *av_alloc_format_context(void); | 503 AVFormatContext *av_alloc_format_context(void); |
437 | 504 |
505 /** | |
506 * Read packets of a media file to get stream information. This | |
507 * is useful for file formats with no headers such as MPEG. This | |
508 * function also computes the real frame rate in case of mpeg2 repeat | |
509 * frame mode. | |
510 * The logical file position is not changed by this function; | |
511 * examined packets may be buffered for later processing. | |
512 * | |
513 * @param ic media file handle | |
514 * @return >=0 if OK. AVERROR_xxx if error. | |
515 * @todo let user decide somehow what information is needed so we dont waste time geting stuff the user doesnt need | |
516 */ | |
438 int av_find_stream_info(AVFormatContext *ic); | 517 int av_find_stream_info(AVFormatContext *ic); |
518 | |
519 /** | |
520 * Read a transport packet from a media file. | |
521 * | |
522 * This function is absolete and should never be used. | |
523 * Use av_read_frame() instead. | |
524 * | |
525 * @param s media file handle | |
526 * @param pkt is filled | |
527 * @return 0 if OK. AVERROR_xxx if error. | |
528 */ | |
439 int av_read_packet(AVFormatContext *s, AVPacket *pkt); | 529 int av_read_packet(AVFormatContext *s, AVPacket *pkt); |
530 | |
531 /** | |
532 * Return the next frame of a stream. | |
533 * | |
534 * The returned packet is valid | |
535 * until the next av_read_frame() or until av_close_input_file() and | |
536 * must be freed with av_free_packet. For video, the packet contains | |
537 * exactly one frame. For audio, it contains an integer number of | |
538 * frames if each frame has a known fixed size (e.g. PCM or ADPCM | |
539 * data). If the audio frames have a variable size (e.g. MPEG audio), | |
540 * then it contains one frame. | |
541 * | |
542 * pkt->pts, pkt->dts and pkt->duration are always set to correct | |
543 * values in AV_TIME_BASE unit (and guessed if the format cannot | |
544 * provided them). pkt->pts can be AV_NOPTS_VALUE if the video format | |
545 * has B frames, so it is better to rely on pkt->dts if you do not | |
546 * decompress the payload. | |
547 * | |
548 * @return 0 if OK, < 0 if error or end of file. | |
549 */ | |
440 int av_read_frame(AVFormatContext *s, AVPacket *pkt); | 550 int av_read_frame(AVFormatContext *s, AVPacket *pkt); |
551 | |
552 /** | |
553 * Seek to the key frame at timestamp. | |
554 * 'timestamp' in 'stream_index'. | |
555 * @param stream_index If stream_index is (-1), a default | |
556 * stream is selected, and timestamp is automatically converted | |
557 * from AV_TIME_BASE units to the stream specific time_base. | |
558 * @param timestamp timestamp in AVStream.time_base units | |
559 * or if there is no stream specified then in AV_TIME_BASE units | |
560 * @param flags flags which select direction and seeking mode | |
561 * @return >= 0 on success | |
562 */ | |
441 int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp, int flags); | 563 int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp, int flags); |
564 | |
565 /** | |
566 * start playing a network based stream (e.g. RTSP stream) at the | |
567 * current position | |
568 */ | |
442 int av_read_play(AVFormatContext *s); | 569 int av_read_play(AVFormatContext *s); |
570 | |
571 /** | |
572 * Pause a network based stream (e.g. RTSP stream). | |
573 * | |
574 * Use av_read_play() to resume it. | |
575 */ | |
443 int av_read_pause(AVFormatContext *s); | 576 int av_read_pause(AVFormatContext *s); |
577 | |
578 /** | |
579 * Close a media file (but not its codecs). | |
580 * | |
581 * @param s media file handle | |
582 */ | |
444 void av_close_input_file(AVFormatContext *s); | 583 void av_close_input_file(AVFormatContext *s); |
584 | |
585 /** | |
586 * Add a new stream to a media file. | |
587 * | |
588 * Can only be called in the read_header() function. If the flag | |
589 * AVFMTCTX_NOHEADER is in the format context, then new streams | |
590 * can be added in read_packet too. | |
591 * | |
592 * @param s media file handle | |
593 * @param id file format dependent stream id | |
594 */ | |
445 AVStream *av_new_stream(AVFormatContext *s, int id); | 595 AVStream *av_new_stream(AVFormatContext *s, int id); |
596 | |
597 /** | |
598 * Set the pts for a given stream. | |
599 * | |
600 * @param s stream | |
601 * @param pts_wrap_bits number of bits effectively used by the pts | |
602 * (used for wrap control, 33 is the value for MPEG) | |
603 * @param pts_num numerator to convert to seconds (MPEG: 1) | |
604 * @param pts_den denominator to convert to seconds (MPEG: 90000) | |
605 */ | |
446 void av_set_pts_info(AVStream *s, int pts_wrap_bits, | 606 void av_set_pts_info(AVStream *s, int pts_wrap_bits, |
447 int pts_num, int pts_den); | 607 int pts_num, int pts_den); |
448 | 608 |
449 #define AVSEEK_FLAG_BACKWARD 1 ///< seek backward | 609 #define AVSEEK_FLAG_BACKWARD 1 ///< seek backward |
450 #define AVSEEK_FLAG_BYTE 2 ///< seeking based on position in bytes | 610 #define AVSEEK_FLAG_BYTE 2 ///< seeking based on position in bytes |
451 #define AVSEEK_FLAG_ANY 4 ///< seek to any frame, even non keyframes | 611 #define AVSEEK_FLAG_ANY 4 ///< seek to any frame, even non keyframes |
452 | 612 |
453 int av_find_default_stream_index(AVFormatContext *s); | 613 int av_find_default_stream_index(AVFormatContext *s); |
614 | |
615 /** | |
616 * Gets the index for a specific timestamp. | |
617 * @param flags if AVSEEK_FLAG_BACKWARD then the returned index will correspond to | |
618 * the timestamp which is <= the requested one, if backward is 0 | |
619 * then it will be >= | |
620 * if AVSEEK_FLAG_ANY seek to any frame, only keyframes otherwise | |
621 * @return < 0 if no such timestamp could be found | |
622 */ | |
454 int av_index_search_timestamp(AVStream *st, int64_t timestamp, int flags); | 623 int av_index_search_timestamp(AVStream *st, int64_t timestamp, int flags); |
624 | |
625 /** | |
626 * Add a index entry into a sorted list updateing if it is already there. | |
627 * | |
628 * @param timestamp timestamp in the timebase of the given stream | |
629 */ | |
455 int av_add_index_entry(AVStream *st, | 630 int av_add_index_entry(AVStream *st, |
456 int64_t pos, int64_t timestamp, int size, int distance, int flags); | 631 int64_t pos, int64_t timestamp, int size, int distance, int flags); |
632 | |
633 /** | |
634 * Does a binary search using av_index_search_timestamp() and AVCodec.read_timestamp(). | |
635 * this isnt supposed to be called directly by a user application, but by demuxers | |
636 * @param target_ts target timestamp in the time base of the given stream | |
637 * @param stream_index stream number | |
638 */ | |
457 int av_seek_frame_binary(AVFormatContext *s, int stream_index, int64_t target_ts, int flags); | 639 int av_seek_frame_binary(AVFormatContext *s, int stream_index, int64_t target_ts, int flags); |
640 | |
641 /** | |
642 * Updates cur_dts of all streams based on given timestamp and AVStream. | |
643 * | |
644 * Stream ref_st unchanged, others set cur_dts in their native timebase | |
645 * only needed for timestamp wrapping or if (dts not set and pts!=dts) | |
646 * @param timestamp new dts expressed in time_base of param ref_st | |
647 * @param ref_st reference stream giving time_base of param timestamp | |
648 */ | |
458 void av_update_cur_dts(AVFormatContext *s, AVStream *ref_st, int64_t timestamp); | 649 void av_update_cur_dts(AVFormatContext *s, AVStream *ref_st, int64_t timestamp); |
650 | |
651 /** | |
652 * Does a binary search using read_timestamp(). | |
653 * this isnt supposed to be called directly by a user application, but by demuxers | |
654 * @param target_ts target timestamp in the time base of the given stream | |
655 * @param stream_index stream number | |
656 */ | |
459 int64_t av_gen_search(AVFormatContext *s, int stream_index, int64_t target_ts, int64_t pos_min, int64_t pos_max, int64_t pos_limit, int64_t ts_min, int64_t ts_max, int flags, int64_t *ts_ret, int64_t (*read_timestamp)(struct AVFormatContext *, int , int64_t *, int64_t )); | 657 int64_t av_gen_search(AVFormatContext *s, int stream_index, int64_t target_ts, int64_t pos_min, int64_t pos_max, int64_t pos_limit, int64_t ts_min, int64_t ts_max, int flags, int64_t *ts_ret, int64_t (*read_timestamp)(struct AVFormatContext *, int , int64_t *, int64_t )); |
460 | 658 |
461 /* media file output */ | 659 /* media file output */ |
462 int av_set_parameters(AVFormatContext *s, AVFormatParameters *ap); | 660 int av_set_parameters(AVFormatContext *s, AVFormatParameters *ap); |
661 | |
662 /** | |
663 * allocate the stream private data and write the stream header to an | |
664 * output media file | |
665 * | |
666 * @param s media file handle | |
667 * @return 0 if OK. AVERROR_xxx if error. | |
668 */ | |
463 int av_write_header(AVFormatContext *s); | 669 int av_write_header(AVFormatContext *s); |
670 | |
671 /** | |
672 * Write a packet to an output media file. | |
673 * | |
674 * The packet shall contain one audio or video frame. | |
675 * The packet must be correctly interleaved according to the container specification, | |
676 * if not then av_interleaved_write_frame must be used | |
677 * | |
678 * @param s media file handle | |
679 * @param pkt the packet, which contains the stream_index, buf/buf_size, dts/pts, ... | |
680 * @return < 0 if error, = 0 if OK, 1 if end of stream wanted. | |
681 */ | |
464 int av_write_frame(AVFormatContext *s, AVPacket *pkt); | 682 int av_write_frame(AVFormatContext *s, AVPacket *pkt); |
683 | |
684 /** | |
685 * Writes a packet to an output media file ensuring correct interleaving. | |
686 * | |
687 * The packet must contain one audio or video frame. | |
688 * If the packets are already correctly interleaved the application should | |
689 * call av_write_frame() instead as its slightly faster, its also important | |
690 * to keep in mind that completly non interleaved input will need huge amounts | |
691 * of memory to interleave with this, so its prefereable to interleave at the | |
692 * demuxer level | |
693 * | |
694 * @param s media file handle | |
695 * @param pkt the packet, which contains the stream_index, buf/buf_size, dts/pts, ... | |
696 * @return < 0 if error, = 0 if OK, 1 if end of stream wanted. | |
697 */ | |
465 int av_interleaved_write_frame(AVFormatContext *s, AVPacket *pkt); | 698 int av_interleaved_write_frame(AVFormatContext *s, AVPacket *pkt); |
699 | |
700 /** | |
701 * Interleave a packet per DTS in an output media file. | |
702 * | |
703 * Packets with pkt->destruct == av_destruct_packet will be freed inside this function, | |
704 * so they cannot be used after it, note calling av_free_packet() on them is still safe. | |
705 * | |
706 * @param s media file handle | |
707 * @param out the interleaved packet will be output here | |
708 * @param in the input packet | |
709 * @param flush 1 if no further packets are available as input and all | |
710 * remaining packets should be output | |
711 * @return 1 if a packet was output, 0 if no packet could be output, | |
712 * < 0 if an error occured | |
713 */ | |
466 int av_interleave_packet_per_dts(AVFormatContext *s, AVPacket *out, AVPacket *pkt, int flush); | 714 int av_interleave_packet_per_dts(AVFormatContext *s, AVPacket *out, AVPacket *pkt, int flush); |
467 | 715 |
716 /** | |
717 * @brief Write the stream trailer to an output media file and | |
718 * free the file private data. | |
719 * | |
720 * @param s media file handle | |
721 * @return 0 if OK. AVERROR_xxx if error. | |
722 */ | |
468 int av_write_trailer(AVFormatContext *s); | 723 int av_write_trailer(AVFormatContext *s); |
469 | 724 |
470 void dump_format(AVFormatContext *ic, | 725 void dump_format(AVFormatContext *ic, |
471 int index, | 726 int index, |
472 const char *url, | 727 const char *url, |
473 int is_output); | 728 int is_output); |
729 | |
730 /** | |
731 * parses width and height out of string str. | |
732 */ | |
474 int parse_image_size(int *width_ptr, int *height_ptr, const char *str); | 733 int parse_image_size(int *width_ptr, int *height_ptr, const char *str); |
734 | |
735 /** | |
736 * Converts frame rate from string to a fraction. | |
737 * | |
738 * First we try to get an exact integer or fractional frame rate. | |
739 * If this fails we convert the frame rate to a double and return | |
740 * an approximate fraction using the DEFAULT_FRAME_RATE_BASE. | |
741 */ | |
475 int parse_frame_rate(int *frame_rate, int *frame_rate_base, const char *arg); | 742 int parse_frame_rate(int *frame_rate, int *frame_rate_base, const char *arg); |
743 | |
744 /** | |
745 * Converts date string to number of seconds since Jan 1st, 1970. | |
746 * | |
747 * @code | |
748 * Syntax: | |
749 * - If not a duration: | |
750 * [{YYYY-MM-DD|YYYYMMDD}]{T| }{HH[:MM[:SS[.m...]]][Z]|HH[MM[SS[.m...]]][Z]} | |
751 * Time is localtime unless Z is suffixed to the end. In this case GMT | |
752 * Return the date in micro seconds since 1970 | |
753 * | |
754 * - If a duration: | |
755 * HH[:MM[:SS[.m...]]] | |
756 * S+[.m...] | |
757 * @endcode | |
758 */ | |
476 int64_t parse_date(const char *datestr, int duration); | 759 int64_t parse_date(const char *datestr, int duration); |
477 | 760 |
478 int64_t av_gettime(void); | 761 int64_t av_gettime(void); |
479 | 762 |
480 /* ffm specific for ffserver */ | 763 /* ffm specific for ffserver */ |
481 #define FFM_PACKET_SIZE 4096 | 764 #define FFM_PACKET_SIZE 4096 |
482 offset_t ffm_read_write_index(int fd); | 765 offset_t ffm_read_write_index(int fd); |
483 void ffm_write_write_index(int fd, offset_t pos); | 766 void ffm_write_write_index(int fd, offset_t pos); |
484 void ffm_set_write_index(AVFormatContext *s, offset_t pos, offset_t file_size); | 767 void ffm_set_write_index(AVFormatContext *s, offset_t pos, offset_t file_size); |
485 | 768 |
769 /** | |
770 * Attempts to find a specific tag in a URL. | |
771 * | |
772 * syntax: '?tag1=val1&tag2=val2...'. Little URL decoding is done. | |
773 * Return 1 if found. | |
774 */ | |
486 int find_info_tag(char *arg, int arg_size, const char *tag1, const char *info); | 775 int find_info_tag(char *arg, int arg_size, const char *tag1, const char *info); |
487 | 776 |
777 /** | |
778 * Returns in 'buf' the path with '%d' replaced by number. | |
779 | |
780 * Also handles the '%0nd' format where 'n' is the total number | |
781 * of digits and '%%'. | |
782 * | |
783 * @param buf destination buffer | |
784 * @param buf_size destination buffer size | |
785 * @param path numbered sequence string | |
786 * @number frame number | |
787 * @return 0 if OK, -1 if format error. | |
788 */ | |
488 int av_get_frame_filename(char *buf, int buf_size, | 789 int av_get_frame_filename(char *buf, int buf_size, |
489 const char *path, int number); | 790 const char *path, int number); |
791 | |
792 /** | |
793 * Check whether filename actually is a numbered sequence generator. | |
794 * | |
795 * @param filename possible numbered sequence string | |
796 * @return 1 if a valid numbered sequence string, 0 otherwise. | |
797 */ | |
490 int av_filename_number_test(const char *filename); | 798 int av_filename_number_test(const char *filename); |
491 | 799 |
492 /* grab specific */ | 800 /* grab specific */ |
493 int video_grab_init(void); | 801 int video_grab_init(void); |
494 int audio_init(void); | 802 int audio_init(void); |