|
| 1 | +<!DOCTYPE html> |
| 2 | +<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> |
| 3 | +<head> |
| 4 | + <meta charset="utf-8" /> |
| 5 | + <meta name="generator" content="pandoc" /> |
| 6 | + <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" /> |
| 7 | + <title>PyRadio Playlist Validation Guide</title> |
| 8 | + <style> |
| 9 | + body {padding: 2em;} |
| 10 | + @media screen and (max-width: 770px) { |
| 11 | + body {padding: 10px;} |
| 12 | + } |
| 13 | + body {max-width: 750px; margin: auto;} |
| 14 | + h2 {margin-top: 2.5em; border-bottom:1px solid SaddleBrown; color: SaddleBrown;} |
| 15 | + h3 {margin-top: 2em; color: SaddleBrown; text-decoration: underline SaddleBrown} |
| 16 | + h4 {margin: 2em 0 1em 0; color: SaddleBrown; font-size: 1em;} |
| 17 | + h4:before {content: "# "; font-weight: bold; vertical-align: middle;} |
| 18 | + h5 {margin: 2em 0 1em 0; color: SaddleBrown; font-size: 1em;;} |
| 19 | + h5:before {content: "## "; font-weight: bold; vertical-align: middle;} |
| 20 | + p, table, ol, ul {margin-left: .8em;} |
| 21 | + STRONG {color: SaddleBrown;} |
| 22 | + dl {margin: 2em;} |
| 23 | + dd {margin: 1em;} |
| 24 | + dt {font-weight: bold;} |
| 25 | + TABLE {border: 1px solid SaddleBrown; border-collapse: collapse; margin-left: auto; margin-right: auto; border-radius: 5px; -moz-border-radius: 5px; border-collapse:separate; box-shadow: 5px 5px 15px #888888;} |
| 26 | + TH {text-align: left; vertical-align: top; padding: 5px;color: SaddleBrown;border: 1px solid SaddleBrown; background-color: SaddleBrown; color: white;} |
| 27 | + TD {text-align: left; vertical-align: top; padding: 5px 10px;border: 1px solid SaddleBrown;} |
| 28 | + pre { background-color: rgba(245, 245, 245, 1); color: #474747; padding: 1.5em; border: 1px solid #C7C7C7; border-radius: 5px; -moz-border-radius: 5px; -webkit-border-radius: 5px; overflow: auto; box-shadow: 5px 5px 15px #C7C7C7;} |
| 29 | + .task-list {list-style-type: none; padding: 0; margin: 0 0 0 1em ;} |
| 30 | + img{display: block; margin-left: auto; margin-right: auto; max-width: 750px; width: 100%; background:transparent; padding:3px; border:1px solid #999999; border-radius: 5px; -moz-border-radius: 5px; -webkit-border-radius: 5px; box-shadow:5px 5px 15px #888888;} |
| 31 | + .indented {text-indent: -1.5em; padding-left: 1.5em; margin-left: 1em;} |
| 32 | + a{ color: SaddleBrown;} |
| 33 | +a:visited{color: SaddleBrown;} |
| 34 | +</style> |
| 35 | +</head> |
| 36 | +<body> |
| 37 | +<header id="title-block-header"> |
| 38 | +</header> |
| 39 | +<h1 style="color: SaddleBrown" id="pyradio-playlist-validation-guide">PyRadio Playlist Validation Guide</h1> |
| 40 | +<p><strong>PyRadio</strong> provides a powerful playlist validation system, with multi-threading support and host-aware throttling.</p> |
| 41 | +<h2 id="table-of-contents">Table of Contents <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></span></h2> |
| 42 | +<!-- vim-markdown-toc Marked --> |
| 43 | +<ul> |
| 44 | +<li><a href="#overview">Overview</a></li> |
| 45 | +<li><a href="#features">Features</a></li> |
| 46 | +<li><a href="#usage">Usage</a> |
| 47 | +<ul> |
| 48 | +<li><a href="#basic-syntax">Basic Syntax</a></li> |
| 49 | +<li><a href="#validation-options">Validation Options</a></li> |
| 50 | +<li><a href="#validation-modes">Validation Modes</a> |
| 51 | +<ul> |
| 52 | +<li><a href="#mark-mode-(default)">mark mode (default)</a></li> |
| 53 | +<li><a href="#drop-mode">drop mode</a></li> |
| 54 | +</ul></li> |
| 55 | +<li><a href="#usage-examples">Usage Examples</a></li> |
| 56 | +</ul></li> |
| 57 | +<li><a href="#technical-details">Technical Details</a> |
| 58 | +<ul> |
| 59 | +<li><a href="#validation-algorithm">Validation Algorithm</a></li> |
| 60 | +<li><a href="#host-aware-throttling">Host-Aware Throttling</a></li> |
| 61 | +<li><a href="#supported-formats">Supported Formats</a></li> |
| 62 | +</ul></li> |
| 63 | +<li><a href="#output-files">Output Files</a> |
| 64 | +<ul> |
| 65 | +<li><a href="#mark-mode">mark mode</a></li> |
| 66 | +<li><a href="#drop-mode">drop mode</a></li> |
| 67 | +</ul></li> |
| 68 | +<li><a href="#results-summary">Results Summary</a></li> |
| 69 | +<li><a href="#usage-tips">Usage Tips</a></li> |
| 70 | +<li><a href="#troubleshooting">Troubleshooting</a></li> |
| 71 | +<li><a href="#contributing">Contributing</a></li> |
| 72 | +</ul> |
| 73 | +<!-- vim-markdown-toc --> |
| 74 | +<p class="indented">[ <a href="index.html#playlist-validation-support">Back to main doc</a> ]</p> |
| 75 | +<h2 id="overview">Overview <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></span></h2> |
| 76 | +<p>This tool allows validation of radio stations in playlist files (CSV or M3U) to ensure all links are functional and provide actual playable audio content.</p> |
| 77 | +<h2 id="features">Features <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></span></h2> |
| 78 | +<ul> |
| 79 | +<li><strong>Multi-threaded validation</strong>: Validate multiple stations simultaneously</li> |
| 80 | +<li><strong>Host-aware throttling</strong>: Limit requests per host to prevent server banning</li> |
| 81 | +<li><strong>Smart audio detection</strong>: Detect actual audio streams through multiple methods</li> |
| 82 | +<li><strong>Flexible output options</strong>: Mark non-functional stations or save to separate files</li> |
| 83 | +<li><strong>Colorized output</strong>: Readable results with color coding</li> |
| 84 | +</ul> |
| 85 | +<h2 id="usage">Usage <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></span></h2> |
| 86 | +<h3 id="basic-syntax">Basic Syntax</h3> |
| 87 | +<pre>pyradio [options] --validate <mode> --convert <playlist_file></pre> |
| 88 | +<h3 id="validation-options">Validation Options</h3> |
| 89 | +<table> |
| 90 | +<thead> |
| 91 | +<tr> |
| 92 | +<th>Option</th> |
| 93 | +<th>Default</th> |
| 94 | +<th>Description</th> |
| 95 | +</tr> |
| 96 | +</thead> |
| 97 | +<tbody> |
| 98 | +<tr> |
| 99 | +<td>–validate</td> |
| 100 | +<td>mark</td> |
| 101 | +<td>Validation mode (<strong>mark</strong> or <strong>drop</strong>)</td> |
| 102 | +</tr> |
| 103 | +<tr> |
| 104 | +<td>–threads</td> |
| 105 | +<td>5</td> |
| 106 | +<td>Number of threads for parallel processing</td> |
| 107 | +</tr> |
| 108 | +<tr> |
| 109 | +<td>–timeout</td> |
| 110 | +<td>5</td> |
| 111 | +<td>Timeout in seconds per request</td> |
| 112 | +</tr> |
| 113 | +<tr> |
| 114 | +<td>–max-per-host</td> |
| 115 | +<td>2</td> |
| 116 | +<td>Maximum concurrent requests per host</td> |
| 117 | +</tr> |
| 118 | +<tr> |
| 119 | +<td>–with-date</td> |
| 120 | +<td>False</td> |
| 121 | +<td>Add timestamp to output filenames</td> |
| 122 | +</tr> |
| 123 | +<tr> |
| 124 | +<td>–no-color</td> |
| 125 | +<td>False</td> |
| 126 | +<td>Disable color output</td> |
| 127 | +</tr> |
| 128 | +<tr> |
| 129 | +<td>–quiet</td> |
| 130 | +<td>False</td> |
| 131 | +<td>Reduce verbosity (hide per-station output)</td> |
| 132 | +</tr> |
| 133 | +</tbody> |
| 134 | +</table> |
| 135 | +<h3 id="validation-modes">Validation Modes</h3> |
| 136 | +<h4 id="mark-mode-default">mark mode (default)</h4> |
| 137 | +<p>Marks non-functional stations with “<em>[X]</em>” in the name and saves all results to one file.</p> |
| 138 | +<pre>pyradio --validate --convert my_playlist.csv</pre> |
| 139 | +<h4 id="drop-mode">drop mode</h4> |
| 140 | +<p>Creates two separate files: - <strong>.ok</strong>: Working stations - <strong>.bad</strong>: Non-working stations</p> |
| 141 | +<p>Example:</p> |
| 142 | +<pre>pyradio --validate drop my_playlist.m3u</pre> |
| 143 | +<h3 id="usage-examples">Usage Examples</h3> |
| 144 | +<p><strong>Basic validation:</strong></p> |
| 145 | +<pre>pyradio --validate mark --convert playlist.csv</pre> |
| 146 | +<p><strong>Validation with 10 threads and stricter timeout:</strong></p> |
| 147 | +<pre>pyradio --validate drop --threads 10 --timeout 3 --convert playlist.m3u</pre> |
| 148 | +<p><strong>Validation with timestamp and without colors:</strong></p> |
| 149 | +<pre>pyradio --validate mark --with-date --no-color --convert playlist.csv</pre> |
| 150 | +<p><strong>Quiet validation (summary only):</strong></p> |
| 151 | +<pre>pyradio --validate mark --quiet --convert playlist.m3u</pre> |
| 152 | +<h2 id="technical-details">Technical Details <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></span></h2> |
| 153 | +<h3 id="validation-algorithm">Validation Algorithm</h3> |
| 154 | +<p>The tool uses multiple techniques to determine if a URL provides actual audio stream:</p> |
| 155 | +<ol type="1"> |
| 156 | +<li><strong>Content-Type check</strong>: Verifies content type is audio/video</li> |
| 157 | +<li><strong>ICY headers detection</strong>: Checks for Shoutcast/Icecast headers</li> |
| 158 | +<li><strong>Audio signature analysis</strong>: Detects patterns of common audio formats (MP3, AAC, OGG, FLAC, etc.)</li> |
| 159 | +<li><strong>HTML exclusion</strong>: Rejects HTML responses indicating errors or pages</li> |
| 160 | +</ol> |
| 161 | +<h3 id="host-aware-throttling">Host-Aware Throttling</h3> |
| 162 | +<p>To prevent server banning, the tool: - Groups requests by hostname - Applies separate semaphore for each host - Limits concurrent requests per host (default: 2)</p> |
| 163 | +<h3 id="supported-formats">Supported Formats</h3> |
| 164 | +<ul> |
| 165 | +<li><strong>CSV</strong>: Files with <strong>PyRadio</strong> CSV formatting</li> |
| 166 | +<li><strong>M3U</strong>: Standard M3U playlist files</li> |
| 167 | +</ul> |
| 168 | +<p style="margin: 1.5em 4em 0 4em; text-indent: -2.5em;"><strong>Note:</strong> If you provide a URL instead of a file path, <strong>PyRadio</strong> will treat it as a link to an online M3U file and attempt to download and validate it.</p> |
| 169 | +<h2 id="output-files">Output Files <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></span></h2> |
| 170 | +<h3 id="mark-mode">mark mode</h3> |
| 171 | +<ul> |
| 172 | +<li>“<em>playlist.validated.[timestamp].csv/m3u</em>”: File with marked non-functional stations</li> |
| 173 | +</ul> |
| 174 | +<h3 id="drop-mode-1">drop mode</h3> |
| 175 | +<ul> |
| 176 | +<li>“<em>playlist.ok.[timestamp].csv/m3u</em>”: Working stations</li> |
| 177 | +<li>“<em>playlist.bad.[timestamp].csv/m3u</em>”: Non-working stations</li> |
| 178 | +</ul> |
| 179 | +<h2 id="results-summary">Results Summary <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></span></h2> |
| 180 | +<p>The tool displays a detailed summary including:</p> |
| 181 | +<ul> |
| 182 | +<li>Number of online/offline stations</li> |
| 183 | +<li>Number of groups (group headers)</li> |
| 184 | +<li>Success rate</li> |
| 185 | +<li>Total counts</li> |
| 186 | +</ul> |
| 187 | +<h2 id="usage-tips">Usage Tips <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></span></h2> |
| 188 | +<ol type="1"> |
| 189 | +<li><strong>For large playlists</strong>: Use more threads (“<em>–threads</em>”) for faster processing</li> |
| 190 | +<li><strong>For sensitive servers</strong>: Reduce “<em>–max-per-host</em>” to avoid banning</li> |
| 191 | +<li><strong>For scheduled validations</strong>: Use “<em>–with-date</em>” for history</li> |
| 192 | +<li><strong>For scripting</strong>: Use “<em>–no-color –quiet</em>” for machine-readable output</li> |
| 193 | +</ol> |
| 194 | +<h2 id="troubleshooting">Troubleshooting <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></span></h2> |
| 195 | +<p><strong>Error: “Cannot write file”</strong> - Ensure you have write permissions in the directory</p> |
| 196 | +<p><strong>Error: “Unsupported file type”</strong> - Ensure the file has <strong>.csv</strong> or <strong>.m3u</strong> extension</p> |
| 197 | +<p><strong>Many non-functional stations</strong> - Check your network connection - Increase “<em>–timeout</em>” for slow servers - Check if stations require specific headers/referrer</p> |
| 198 | +<h2 id="contributing">Contributing <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></span></h2> |
| 199 | +<p>Any improvements to the validation algorithm or new detection techniques are welcome.</p> |
| 200 | +</body> |
| 201 | +</html> |
0 commit comments