ytextractor – pobieranie i konwersja audio/wideo z YouTube z poziomu konsoli

ytextractor to zaawansowane narzędzie konsolowe napisane w Pythonie, służące do pobierania i konwertowania materiałów audio oraz wideo z serwisu YouTube. Program stanowi wygodne opakowanie (wrapper) dla dwóch znakomitych narzędzi: yt-dlp (silnik pobierania) oraz FFmpeg (konwersja i łączenie strumieni).

GitHub: github.com/IgorBrzezek/ytextractor

Do czego służy ytextractor?

Program ma dwa podstawowe zadania:

• Ekstrakcja audio – pobranie ścieżki dźwiękowej z filmu YouTube i konwersja do formatu MP3 w różnych jakościach (od oszczędnego mono po wysokiej jakości stereo VBR).
• Pobieranie wideo – ściągnięcie całego filmu z dźwiękiem w rozdzielczościach 480p, 720p lub 1080p i zapis w formacie MP4.

ytextractor świetnie sprawdza się w wielu sytuacjach:

• Tworzenie biblioteki muzycznej – pobieranie ulubionych utworów z YouTube w formacie MP3.
• Archiwizacja materiałów szkoleniowych – zapisywanie kursów i tutoriali wideo do późniejszego odtwarzania offline.
• Przetwarzanie wsadowe – pobieranie całej listy linków z pliku tekstowego w jednym przebiegu.
• Automatyzacja zadań – tryb cichy (-b, –batch) idealny do skryptów i zadań cron.

Jak to działa – mechanizm wewnętrzny

ytextractor po podaniu URL-i wykonuje następujące kroki:

1. Pobranie metadanych – program uruchamia yt-dlp z opcją --dump-json, aby uzyskać informacje o filmie: tytuł, czas trwania, dostępne strumienie.
2. Pobranie strumienia – w zależności od wybranego formatu (audio lub wideo) yt-dlp pobiera odpowiednie strumienie z YouTube.
3. Konwersja (dla audio) – jeśli wybrano format MP3, FFmpeg konwertuje pobrany strumień audio na zadany format (stereo/mono, różne przepływności VBR).
4. Łączenie strumieni (dla wideo) – dla opcji wideo yt-dlp pobiera osobno strumień obrazu i dźwięku, a następnie łączy je w jeden plik MP4 bez ponownego kodowania (najszybsza metoda).
5. Zapis pliku – gotowy plik trafia do wskazanego katalogu (domyślnie bieżący folder).

Program obsługuje interaktywny wybór akcji w przypadku istniejących plików: [y/N/a/q] – nadpisz, pomiń, nadpisz wszystkie lub wyjdź. Nieudane lub niekompletne pobrania są rejestrowane w pliku ytextractor.err.

Wymagania

Przed uruchomieniem programu należy zapewnić następujące zależności:

• Python 3 – wraz z biblioteką colorama (opcjonalna, do kolorowania terminala). Instalacja: pip install colorama.
• yt-dlp – główny silnik pobierania. Należy go bieżąco aktualizować, ponieważ YouTube często zmienia swoją stronę. Instalacja: pip install yt-dlp lub winget install yt-dlp (Windows).
• FFmpeg i FFprobe – wymagane do konwersji audio i łączenia plików MP4. Pobranie ze strony ffmpeg.org.

Program musi mieć dostęp do tych narzędzi przez zmienną środowiskową PATH.

Instalacja i uruchomienie

Wystarczy pobrać plik yt_avextractor.py z repozytorium GitHub i uruchomić z konsoli:

python yt_avextractor.py [OPCJE] "URL_1" "URL_2" ...

Do przetwarzania wsadowego z pliku:

python yt_avextractor.py --list "lista_linkow.txt" [OPCJE]

Uwaga: URL-e zawsze należy umieszczać w cudzysłowie („”), aby uniknąć błędów interpretacji znaków specjalnych (np. & w adresach playlist).

Opcje wiersza poleceń – szczegółowy opis

Pomoc

Opcja	Opis
-h, --short-help	Krótka, jednoliniowa pomoc.
--help	Rozszerzona, kategoryzowana pomoc z przykładami.

Wejście i wyjście

Opcja	Opis	Domyślnie
urls	Jeden lub więcej URL-i YouTube (ignorowane przy –list).	–
-o, --output NAZWA	Niestandardowa nazwa pliku (tylko dla pojedynczego URL).	–
--list PLIK	Ścieżka do pliku z listą URL-i (jeden na linię).	–
--skip	Pomija istniejące pliki bez pytania.	–
-dst KATALOG	Katalog docelowy dla plików.	bieżący
--overwrite	Nadpisuje istniejące pliki bez pytania.	pyta

Format (audio)

Opcja	Opis
-mp3high (domyślny)	MP3 stereo VBR 192 kbps.
-mp3fast	MP3 stereo VBR 128 kbps (szybkie kodowanie).
-mp3slow	MP3 stereo VBR 196 kbps (wysoka jakość).
-mono	MP3 mono VBR 96 kbps (oszczędność miejsca).

Format (wideo)

Opcja	Opis
-mp4fast	MP4 720p (najszybsza metoda).
-mp41080	MP4 1080p lub najlepsza dostępna.
-mp4480	MP4 480p lub najlepsza dostępna.

Antyblokowanie

Opcja	Opis
--cookies PRZEGLĄDARKA	Używa ciasteczek z przeglądarki (np. chrome, firefox). Rozwiązuje blokady 403.
-r, --limit-rate PRĘDKOŚĆ	Ogranicza prędkość pobierania (np. 500K, 4.2M).
--add-header	Dodaje standardowy nagłówek User-Agent przeglądarki.
--add-android	Symuluje zapytanie z oficjalnej aplikacji YouTube na Androida.

Tryb wyświetlania

Opcja	Opis
--pb	Szczegółowy pasek postępu z yt-dlp.
--min	Minimalny, jednoliniowy postęp.
-b, --batch	Tryb cichy – brak komunikatów w konsoli.
--compact	Zwarty widok dla opcji –list.
-sum, --summarize	Wyświetla podsumowanie po zakończeniu wsadu.
--title	Pokazuje tytuł każdego pobieranego pliku.
--showname X	W trybie –min pokazuje X pierwszych znaków tytułu.

Narzędzia

Opcja	Opis
--color	Koloruje wyjście terminala.
--log [NAZWA]	Zapisuje log yt-dlp do pliku (domyślnie yt-dlp.log).
--debug	Pokazuje surowe wyjście yt-dlp i ffmpeg.
--verbose	Tryb szczegółowy.
-t, --threads N	Liczba wątków FFmpeg do kompresji (domyślnie: 1).
-ret, --retries N	Liczba prób ponowienia nieudanego pobrania (domyślnie: 1).

Zarządzanie yt-dlp

Opcja	Opis
--dlver	Pokazuje aktualną wersję yt-dlp.
--dlchk	Sprawdza najnowszą dostępną wersję yt-dlp online.
--dlupg	Aktualizuje yt-dlp do najnowszej wersji (automatycznie, w zależności od systemu).

Przykłady użycia

1. Pobranie audio w wysokiej jakości (stereo 196 kbps)

python yt_avextractor.py -mp3slow --color "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Pobiera najlepszą dostępną ścieżkę dźwiękową i konwertuje ją do MP3 stereo VBR 196 kbps. Opcja –color włącza kolorowanie wyjścia.

2. Pobranie audio z listy linków zwartym widokiem i podsumowaniem

python yt_avextractor.py --list music.txt --compact --summarize --title --color

Przetwarza plik music.txt, pokazuje zwięzłe aktualizacje dla każdego pliku, końcowe podsumowanie oraz tytuły utworów.

3. Szybkie pobranie wideo 720p z użyciem ciasteczek przeglądarki

python yt_avextractor.py -mp4fast --cookies chrome "https://www.youtube.com/watch?v=VIDEO_ID"

Pobiera obraz i dźwięk do 720p i łączy je w plik MP4 bez przekodowywania. Ciasteczka Chrome pomagają ominąć blokady regionalne i ograniczenia wiekowe.

4. Pobranie wideo 1080p z 4 wątkami FFmpeg

python yt_avextractor.py -mp41080 -t 4 --color "https://www.youtube.com/watch?v=VIDEO_ID"

Pobiera strumienie w jakości 1080p, używając 4 wątków procesora do ewentualnego przetwarzania końcowego.

5. Pobranie mono MP3 (oszczędność miejsca) z 3 próbami ponowienia

python yt_avextractor.py -mono -ret 3 "https://www.youtube.com/watch?v=VIDEO_ID"

Konwertuje dźwięk do pojedynczego kanału (mono) z przepływnością 96 kbps. Jeśli pobranie się nie powiedzie, program podejmie do 3 prób.

6. Przetwarzanie wsadowe z pomijaniem istniejących plików

python yt_avextractor.py --list downloads.txt --skip --color

Automatycznie pomija pliki, które już istnieją w folderze docelowym, bez zadawania pytań.

Zarządzanie plikami tymczasowymi

Od wersji 1.20 wszystkie pliki tymczasowe używają prefiksu ytextr_tmp_, co ułatwia ich identyfikację. Program automatycznie sprząta pozostałe pliki tymczasowe przy starcie oraz podczas normalnego działania, zapobiegając ich gromadzeniu się na dysku.

Najczęstsze problemy i ich rozwiązania

• Błąd 403 Forbidden / ograniczenia wiekowe – użyj opcji --cookies chrome (lub innej przeglądarki). To rozwiązuje problem w 99% przypadków.
• Skrypt nie działa – wszystkie pobrania kończą się błędem – Twój yt-dlp jest nieaktualny. Wykonaj yt-dlp -U lub użyj opcji --dlupg wbudowanej w program.
• „ffmpeg: command not found” – FFmpeg nie znajduje się w zmiennej PATH. Pobierz go z ffmpeg.org i dodaj do PATH.
• URL-e z & (np. playlisty) powodują błędy – zapomniałeś umieścić URL w cudzysłowie („”).
• Nie udało się pobrać niektórych plików w trybie wsadowym – sprawdź plik ytextractor.err w katalogu programu. Zawiera on listę nieudanych URL-i wraz z przyczyną błędu.

Zatrzymywanie programu

Program można bezpiecznie zatrzymać naciskając Ctrl+C. ytextractor obsługuje sygnał SIGINT – natychmiast kończy procesy potomne (yt-dlp, ffmpeg) i usuwa niekompletne pliki. Przy starcie program automatycznie usuwa pozostałe pliki tymczasowe z poprzednich sesji.

Podsumowanie

ytextractor to solidne i elastyczne narzędzie konsolowe do pobierania materiałów z YouTube. Dzięki wykorzystaniu sprawdzonych silników (yt-dlp i FFmpeg) oferuje wysoką niezawodność i bogaty zestaw opcji konfiguracyjnych. Obsługa pojedynczych URL-i i przetwarzania wsadowego, różne formaty audio i wideo, mechanizmy antyblokujące oraz interaktywny wybór akcji dla istniejących plików czynią go uniwersalnym rozwiązaniem zarówno do jednorazowych pobrań, jak i do zautomatyzowanych procesów.

Wersja ANSI C (samodzielna) nie jest dostępna – program działa wyłącznie w Pythonie. Źródła: github.com/IgorBrzezek/ytextractor.