774706c41b75ab77842d9700fd63f55529b2bca9
[ffmpeg-web.git] / src / bugreports
1 <h1>Reporting a Bug To The FFmpeg Project</h1>
2
3 <p>
4 <b>Before reporting a bug, please consider the following items</b>:
5 </p>
6
7 <p>
8 FFmpeg is in a state of perpetual development. As such, if you wish to
9 query or report a bug, you must try with the <b>latest development branch</b> revision of
10 FFmpeg to confirm the issue still exists.
11 </p>
12
13 <p>
14 When writing your bug report, please include (uncompressed):
15 </p>
16 <ul>
17   <li>What you were trying to accomplish (e.g., "I am trying to transcode
18     from this format to that format...")</li>
19   <li>The problem you encountered (e.g., "<code>ffmpeg</code> crashed, see the
20       gdb and valgrind output below" or "The
21     output video was all green")</li>
22   <li>The exact command line you were using (e.g., "<code>ffmpeg -i input.mov
23     -an -vcodec foo output.avi</code>")</li>
24   <li>The full, uncut console output provided by
25     <code>ffmpeg -v 9 -loglevel 99 -i </code> followed by the name of your input file
26     (copy/pasted from the console, including the banner that indicates
27     version and configuration options), paste <code>ffplay</code> output
28     only if your problem is not reproducible with ffmpeg.</li>
29   <li>Sufficient information, including any required input files, to reproduce
30     the bug and confirm a potential fix.</li>
31 </ul>
32
33 <p>
34 You can use the <code>-report</code> option or define the
35 <code>FFREPORT</code> environment variable (to any value) to get the exact
36 command line and the full verbose console output in a file named
37 <code>ffmpeg-*.log</code> in the current directory.
38 Note that the <code>-report</code> option is recent, it will not help
39 tracking regressions in old revisions.
40 </p>
41
42 <p>
43 If you encounter a crash bug, please provide the <code>gdb</code> output,
44 backtrace and disassembly, and if possible the <code>valgrind</code> output,
45 using the the <code>ffmpeg_g</code> debug binary.
46 </p>
47
48 <p>
49 For <code>gdb</code>, proceed as follows:
50 </p>
51
52 <blockquote>
53 <pre>gdb ffmpeg_g</pre>
54 </blockquote>
55
56 <p>
57 In <code>gdb</code>, type 'r' for run, along with the rest of the
58 <code>ffmpeg</code> command line:
59 </p>
60
61 <blockquote>
62 <pre>r &lt;rest of command line&gt;</pre>
63 </blockquote>
64
65 <p>
66 (Alternatively, you can run <code>gdb --args ffmpeg_g &lt;rest of command
67 line&gt;</code> and just type 'r' at the <code>gdb</code> prompt.)
68 </p>
69
70 <p>
71 When <code>gdb</code> encounters its problem, run the following commands and
72 copy/paste the output into your bug report:
73 </p>
74
75 <blockquote>
76 <pre>
77 bt
78 disass $pc-32,$pc+32
79 info all-registers
80 </pre>
81 </blockquote>
82 <p>
83 With older <code>gdb</code> versions, use <code>disass $pc-32 $pc+32</code>.
84 </p>
85
86 <p>
87 For <code>valgrind</code>, run the following command and copy/paste the
88 output into your bug report:
89 </p>
90
91 <blockquote>
92 <pre>valgrind ffmpeg_g &lt;rest of command line&gt;</pre>
93 </blockquote>
94
95 <h2 id="BugTracker">Bug Tracker</h2>
96
97 <p>
98 Once you have gathered this information, you can submit a report to the
99 <a href="https://trac.ffmpeg.org">FFmpeg bug tracker</a>.
100 Note, you must <a href="https://trac.ffmpeg.org/register">register</a>
101 there first before you can submit a report.
102 You should provide all information so that anyone can reproduce the bug.
103 Please do not report your problem on the developer mailing list:
104 Only send bug reports there if you also intend to provide a fix.
105 </p>
106
107
108 <h2 id="SubmittingSampleMedia">Submitting Sample Media</h2>
109
110 <p>
111 The developers may ask you to provide a sample media file illustrating
112 your problem. In this case, please follow these steps:
113 </p>
114 <ul>
115   <li>If the sample file is too large ( &gt; 10 megabytes), cut it down to
116     size with the Unix 'dd' command:
117       <blockquote>
118       <pre>dd if=sample-file of=small-sample-file bs=1024 count=10000</pre>
119       </blockquote>
120     and then upload small-sample-file rather than sample-file</li>
121   <li>Please choose descriptive names like "h264_green_tint.mov" or
122       "block_artifacts_after_seeking.mkv". We already have plenty of "bug.rm"
123       and "sample.avi".</li>
124   <li>Upload the sample to the FTP server. Note that our FTP server
125     is write-only. Even though you cannot see the files that you upload,
126     it will be there and the FFmpeg developers will have access.
127   <ul>
128     <li>Log into upload.ffmpeg.org with an anonymous FTP login.</li>
129     <li>cd -> incoming</li>
130     <li>Upload a brief text file describing the sample and what is wrong.
131         <b>This is important!</b> If you leave out the text file, your
132         sample will most likely be deleted without further examination.</li>
133     <li>Upload the sample.</li>
134   </ul>
135   </li>
136   <li>Email the ffmpeg mailing list and indicate the filename of the sample.</li>
137 </ul>
138
139 <p>
140 <b>Important: Movie files which have been compressed (rar,7z,gzip,...) will be
141 deleted without being examined unless they are raw RGB/YUV/PCM.</b>
142 <b>Furthermore movie files uploaded to services like megaupload, rapidshare or
143 any other similar service will be ignored. We are not willing to spend our
144 time fighting with this ridiculous, bloated and spam-filled crap.</b>
145 </p>
146