{"id":30859157,"url":"https://github.com/k4karole/qtea_media_player","last_synced_at":"2025-09-07T14:57:33.590Z","repository":{"id":205828003,"uuid":"696135042","full_name":"K4KarolE/QTea_Media_Player","owner":"K4KarolE","description":"Media player with multiple playlists, thumbnail view, cross playlists search and queue management","archived":false,"fork":false,"pushed_at":"2025-09-04T04:13:38.000Z","size":5837,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-04T06:20:53.122Z","etag":null,"topics":["ffmpeg","ffmpeg-python","gui","media-player","mediaplayer","music-player","pyqt","pyqt5","pyqt5-gui","pyqt6","pyqt6-gui","python","python3","thumbnail","thumbnail-generator","video","video-player","vlc","vlc-media-player","winamp"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/K4KarolE.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-09-25T06:49:55.000Z","updated_at":"2025-09-04T04:13:41.000Z","dependencies_parsed_at":"2023-12-30T05:24:07.370Z","dependency_job_id":"4166ee1e-53d8-43a8-aa7c-0e9adc5f7913","html_url":"https://github.com/K4KarolE/QTea_Media_Player","commit_stats":null,"previous_names":["k4karole/music_player","k4karole/qtea_media_player"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/K4KarolE/QTea_Media_Player","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/K4KarolE%2FQTea_Media_Player","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/K4KarolE%2FQTea_Media_Player/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/K4KarolE%2FQTea_Media_Player/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/K4KarolE%2FQTea_Media_Player/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/K4KarolE","download_url":"https://codeload.github.com/K4KarolE/QTea_Media_Player/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/K4KarolE%2FQTea_Media_Player/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274051985,"owners_count":25214030,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ffmpeg","ffmpeg-python","gui","media-player","mediaplayer","music-player","pyqt","pyqt5","pyqt5-gui","pyqt6","pyqt6-gui","python","python3","thumbnail","thumbnail-generator","video","video-player","vlc","vlc-media-player","winamp"],"created_at":"2025-09-07T14:57:18.621Z","updated_at":"2025-09-07T14:57:33.579Z","avatar_url":"https://github.com/K4KarolE.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Main features\n- Thirty playlists supported by default. More can be generated.\n- Thumbnail view.\n- Cross playlists queue management with dedicated window.\n- Cross playlists search.\n- Drag \u0026 drop - files, folders.\n- Start media from the latest point.\n- Start the last played media at startup.\n- Quick switch to alternative window mode / size / position.\n- Playlists saved by default.\n- Set video's preferred audio track to default.\n- Hotkeys, right click menus, selectables:\n    - Audio and subtitle tracks\n    - Full screen on the current display or on the selected display\n- QTea media player can be a viable option for highly organised contentgoers and house party DJs.\nInspired by `Winamp`, `VLC media player` and `Total/Double Commander`.\n\n## Guide\n- [Screenshots](#screenshots)\n- [Terminology](#terminology)\n- [Buttons](#buttons)\n    - [Play buttons](#play-buttons)\n    - [Playlist buttons](#playlist-buttons-under-playlists-section)\n- [Settings window](#settings-window)\n   - [General](#general)\n   - [Hotkeys](#hotkeys)\n   - [Playlists](#playlists)\n- [Active and Playing playlists separation](#active-and-playing-playlists-separation)\n- [Thumbnail View](#thumbnail-view)\n- [Increase the number of playlists beyond the default](#steps-to-increase-the-number-of-playlists-beyond-the-default--to-generate-new-playlist-database)\n- [Other Behaviour](#other-behaviour)\n    - Volume\n    - Screen saver\n    - Drag \u0026 Drop\n- [File types](#file-types)\n- [Workarounds](#workarounds)\n    - [Dummy track](#dummy-track)\n    - [Dummy playlist tab](#dummy-playlist-tab)\n    - [Information displayed as subtitle](#information-displayed-as-subtitle)\n    - [Audio delay - LINUX only](#audio-delay---linux-only)\n    - [No solution yet](#could-not-find-solution-yet)\n- [Requirements](#requirements)\n\n## Screenshots\n\u003cdiv align=\"left\"\u003e\n    \u003cimg src=\"https://github.com/user-attachments/assets/5f8abf75-7f97-48d8-a979-30550915a306\"\u003e\n\u003c/div\u003e\n\u003cbr\u003e\n\u003cdiv align=\"left\"\u003e\n    \u003cimg src=\"https://github.com/user-attachments/assets/d9334f75-d459-4354-8401-7b33b33fe25e\"\u003e\n\u003c/div\u003e\n\u003cbr\u003e\n\u003cdiv align=\"left\"\u003e\n    \u003cimg src=\"https://github.com/user-attachments/assets/7b956b27-5a1d-4c37-94a5-2e9a0a4905d0\"\u003e\n\u003c/div\u003e\n\u003cbr\u003e\n\u003cdiv align=\"left\"\u003e\n    \u003cimg src=\"https://github.com/user-attachments/assets/67521950-75c7-4767-924a-dbd16e31620c\"\u003e\n\u003c/div\u003e\n\u003cbr\u003e\n\u003cdiv align=\"left\"\u003e\n    \u003cimg src=\"https://github.com/user-attachments/assets/1acf7a47-ffd5-4586-ae63-c49a31b13c2d\"\u003e\n\u003c/div\u003e\n\u003cbr\u003e\n\u003cdiv align=\"left\"\u003e\n    \u003cimg src=\"https://github.com/user-attachments/assets/577c5064-e2ff-4789-9a0a-d63925c9153e\"\u003e\n\u003c/div\u003e\n\u003cbr\u003e\n\u003cdiv align=\"left\"\u003e\n    \u003cimg src=\"https://github.com/user-attachments/assets/4c99a7c8-95f8-4281-b935-9c4c0fb3b4a2\"\u003e\n\u003c/div\u003e\n\u003cbr\u003e\n\n\n## Terminology\n- `Playing playlist`: playlist, where the current track is in the playing or paused state / \nplaylist where the last track was played.\n- `Active playlist`: playlist, which is currently selected / displayed.\n- `Thumbnail playlist`: playlist, where the thumbnail generation thread is running on\n\n## Buttons\n### Play buttons\n- The `Play`, `Stop`, `Previous track`, `Next track` and `Shuffle` buttons behave as usual\n  - When `Shuffle` is on, the played media is tracked. If no switch between playlists has been made,\nthe last \"X\" tracks can be played back when the `Previous track` button/hotkey is triggered.\n    - The amount \"X\" declared in `src / class_data / shuffle_played_tracks_list_size`.\n- The `Repeat playlist` button has 3 states:\n    - Disabled\n    - Repeat playlist - the button is flat.\n    - Repeat currently playing track - the button is flat and a square shape displayed in the middle of the icon.\n- `Toggle Video and Playlist` buttons show/hide the video or playlist section.\n    - Can not hide both the same time.\n    - At startup both the video and playlist section are visible as default.\n- Tooltip is displayed when the mouse moved over the current button.\n\n### Playlist buttons (under playlists section)\n- `AT - Add Track`: add a single media/file to the playlist.\n- `AD - Add Directory`: adding all the media files listed in the selected directory and subdirectories.\n- `RT - Remove Track`: removes the current/selected track.\n- `CP - Clear Playlist`: removes all the items from the current playlist.\n- `Q`: opens the `Queue and Search Window`\n- `Settings button`: opens the `Settings window`.\n- `Thumbnail View`: switches between the standard and the `Thumbnail View` playlists\n- Tooltip is displayed when the mouse moved over the current button.\n\n## Settings window\n- To open the `Setting window` click on the `Cog/Settings icon` under the playlists section. \n- `Playlists tab:` Able to update the playlists titles - hide/show the playlists.\n- `General tab:` Adjust the media player's and hotkeys' behaviour.\n- `Hotkeys tab:` Adjust the hotkeys' keybinds.\n- Saving the `Settings window` values by clicking on the `Save button`:\n    - Saves all the values from all the tabs (Playlists, General, Hotkeys) if there is no invalid value.\n    - Else: \n        - Pop-up window displayed with the error message for all the fields with invalid value.\n        - Error message includes the name of the field and the rule it should follow.\n        - The pop-up window title: ERROR - TAB'S NAME (where the invalid value occurred).\n\n### General\n- `Always on top`: Keeps the player on top of other currently running applications\n- `Continue playback`:\n    - Saves the duration of the currently playing track every 5 seconds.\n    - When revisiting the same track, the play continuous from the latest, saved position.\n- `Play at startup`:\n    - Automatically plays the last played track at startup.\n    - If the track was removed while playing, at the next startup it plays the track in the same row.\n    - If the last play track removed and there is no track in the same row:\n        - If the playlist is not empty: It plays the first track of the playlist.\n        - If the playlist is empty: No track played.\n- `Small / Medium / Big jump`: \n    - Seconds the player position will be moved (forward/backward)\n    - Hotkeys of the direction/jump type are in the `Hotkeys tab`\n    - Amending the jump values in the `General tab`\n- `Window width-height / alt. / 2nd alt.`:\n    - Values of the different window sizes.\n    - To switch between the different window sizes:\n        - `Window alt. size` hotkey (`Hotkeys tab`) or\n        -  Right-click on the video area (if applicable) and select `Alter - Toggle`\n    - `Window width-height`:\n        - The size of the window at startup.\n        - Both video and playlist section/window are visible.\n    - `Window alt. width-height`: \n        - The size of the window after the window size alter toggle actioned once\n        - Only the video window is visible, the playlist window is hidden.\n    - `Window 2nd alt. width-height`: \n        - The size of the window after the window size alter toggle actioned twice.\n        - Only the video window is visible, the playlist window is hidden.\n    - `Window alt. repositioning`:\n        - Repositioning the window depending on the selected size.\n        - Default and 1st: middle of the screen / 2nd: right, bottom corner of the screen.\n    - `Default audio track`:\n        - Video starts with the selected audio track.\n        - Can be useful while watching multiple episodes of a tv show in one sitting where the preferred audio\n    track is not the first/default one.\n    - `Thumbnail image size`: Min:100, Max:500 pixels.\n    - `Remove unused thumbnails older than (days)`: When closing the app, it removes the unused thumbnails older\n  than the added value and updates the `_thumbnail_history.json` including the logs for the failed /\n  uncreated thumbnails.\n    - `Search result - parent folders' text length`: The separate text length of the 2nd and 1st parent\n    directory of the media in the search result displayed as:\n  2nd degree parent directory(sized) / 1st degree parent directory(sized) - file name\n    - Ideas:\n        - Use the first alt. window size when the user is close to a wide screen (e.g.: having a lunch).\n        - Use the second alt. window size when player is secondary and it can be placed in the right,\nbottom corner of the screen (e.g: while browsing).\n        - Adjust the sizes according the currently played TV show`s video ratio to avoid black bars.\n\n### Hotkeys\n- Acceptable hotkey formats: `M`, `m`, `Ctrl`, `ctRL`, `M+Ctrl`, `M+Ctrl+Space`, `M | P`, `M+Ctrl | P`\n- Able to add multiple hotkeys for the same action: `Up | P`\n- Acceptable hotkey list in `src / cons_and_vars.py / keys_list`\n- `Small / Medium / Big jump - backward/forward`:\n    - The values of the jump types are defined in the `General tab`.\n- `Play\\pause` vs `Play`:\n    - `Play\\pause`:\n        - If a track is in the playing/paused state: pauses or continues to play the track independently\n      from the current active playlist.\n        - If no track is in the playing/paused state: starts the selected track on the active playlist.\n    - `Play`: Starts the selected track on the active playlist even if there is a track in the\n  playing/paused state from any playlist.\n- `Volume - Increase / Decrease`: Changes the volume with +/- 5%.\n- `Audio track - use next`: Toggles between the available audio channels, there is no disabled state.\n- `Subtitle track - use next`: Toggles between the available subtitles and a disabled state.\n- `Toggle - Full screen`: Next to the value set up in this field the `Escape` button is hard-coded to quit\nfrom the full screen mode.\n- `Toggle - Window alt. size`:\n    - Toggles between the default / alt. / 2nd alt. window sizes defined in the `General tab`.\n    - Default: both video and playlist sections are visible.\n    - Alt. and 2nd alt.: only the video section is visible. \n- `Playlist - Select previous / next`: Jumps between the playlists available.\n- `Queue / Dequeue track`:\n    - Add track to / removes track from the queue list.\n    - This hotkey takes action on the `Active playlist`.\n    - On the `Queue and Search window`s track list the right-click / Queue-Dequeue should be used.\n- The rest of the hotkeys are self-explanatory.\n\n### Playlists\n- In the `Settings window / Playlists` tab all playlists are listed.\n    - To make a playlist visible:\n        - Add a title to the playlist.\n        - If the playlist is used the first time: empty playlist will be displayed after saving.\n        - If playlist had tracks before it was hidden: the records will be loaded automatically after restart.\n    - To hide a playlist:\n        - Remove the title of the playlist.\n        - At least one of the playlists remains visible:\n            - Not able to remove all the playlist titles: clicking on the `Save button`: pop-up window will be\n        displayed with the error message.\n        - The hidden playlist's records/media information remains in the database.\n- Able to add/remove tracks to any of playlists: the playlist is saved automatically\n    - At startup:\n        - All playlists loading automatically.\n        - On all playlist the last played track is selected.\n        - The `Playing playlist` is active/displayed.\n\n\u003cdiv align=\"left\"\u003e\n    \u003cimg width=\"260\" src=\"https://github.com/user-attachments/assets/c46365e5-26af-4ad2-b6a3-837636aea9ab\"\u003e\n    \u003cimg width=\"260\" src=\"https://github.com/user-attachments/assets/9172c9ce-f762-4c24-9198-c4e0572ea880\"\u003e\n    \u003cimg width=\"260\" src=\"https://github.com/user-attachments/assets/f0140e2e-eef4-4ca0-8760-eeee17972184\"\u003e\n\u003c/div\u003e\n\u003cbr\u003e\n\n## Active and Playing playlists separation\n- It allows the user to control the `playing or queued tracks playlist` while browsing the rest of the playlists\n- If there is no track in the queue:\n    - All the below steps actioned on the `Playing playlist` even if the active and playing playlists are different:\n        - Paused --\u003e Play\n        - Play previous track\n        - Play next track\n        - Play next track in the playlist automatically after end of the current track\n        - Shuffle / repeat functionalities\n        - All hotkey functionalities: change audio/subtitle track\n- If there are tracks in the queue:\n    - All the above behaviours are actioned on the `queued tracks playlist` (apart from shuffle)\n- Window title = Playing playlist title | Track title\n\n## Thumbnail View\n### General\n- If `FFmpeg` is installed, the `Thumbnail View` button is active under the Playlist area.\n  - Otherwise, the button is inactive and \"FFmpeg installation needed\" message is displayed\nonce the cursor is over the button.\n  - There is more information below in the `Requirements` section.\n- Adding/removing media to/from a playlist where the `Thumbnail View` is active: automatically switching back to the \nstandard playlist view.\n- Once the `Thumbnail View` button is clicked, the thumbnail generation is running for the current playlist until\nit is completed.\n  - Or the `Thumbnail View` button is clicked again \"on\" the same or \"on\" another playlist.\n- The `Thumbnail View` and standard playlist view are in sync regarding the selection and currently playing and\nselected track style.\n### Thumbnail generation\n- Every audio file has the same, default audio thumbnail.\n- Every new thumbnail image is placed in the `thumbnails` folder with a unique title: \n\"filename.ext\".\"raw duration\".\"image size\".jpg\n  - `Image title: current time` key-value pair is added to the `thumbnails / _thumbnail_history.json / completed`.\n  - If the thumbnail generation was unsuccessful, it is logged in the `thumbnails / _thumbnail_history.json / failed` \n  with the `image title: current time` key-value pair.\n- Every thumbnail generation process starts by checking if the image title(key) exists in the \n`_thumbnail_history.json / completed` or in the `failed` dictionary before the actual thumbnail image generation.\n  - In `failed`: not trying to generate thumbnail image, `image title: current time` value will be updated\n  with the current time.\n  - In `completed`: checks if the file exists.\n    - Yes: image will be used for the thumbnail, `image title: current time` value will be updated with the current time.\n    - No: try to generate a new thumbnail image.\n- The \"image taken from point\" is video duration dependent.\n  - Logic in `src / func_thumbnails / get_time_frame_taken_from()`\n\n## Steps to increase the number of playlists beyond the default / to generate new playlist database\n1. Close the app if it is running.\n2. Rename the current playlist database: `playlist.db`.\n3. In the `src / tables_and_playlists_guide.py` file change the `create_tables(playlists_amount = 30)` function's \n`playlists_amount` argument value to as many playlists you wish, save the Python file.\n4. Run the `create_tables()` function -\u003e New `playlist.db` will be created.\n5. After the next start of the app, all the playlists will be visible with increasing numeric titles.\n6. Optional: Change the title of the playlists via the `Settings window / Playlists`.\n7. Optional: Remove the previous playlist database.\n\n## Other Behaviour\n- `Volume`\n    - Changing the volume after the app is muted:\n        - It switches back to the un-muted state.\n        - New volume = volume before muted -/+ the change.\n    - The volume range is less wide compared to `VLC media player`.\n- `Screen saver`\n    - When video window is displayed and video is playing the screen saver is turned off.\n        - Otherwise the screen saver is on as usual.\n- `Drag \u0026 Drop`\n    - Internal: able to relocate/move a playlist item.\n    - External: selected files and/or folders can be grabbed and dropped on the active playlist from\n  File Explorer, Desktop,  .. . \n\n## File types\n- \"formats supported depend heavily on the codec packs installed on your system\" - [link](https://forum.qt.io/topic/63110/)\n- Which files will be added to the playlist when I add a directory?\n    - Every file with the extensions listed in the `src / cons_and_vars.py / FILE TYPES` section will be added:\n        - `FILE_TYPES_LIST` used to sort the files in the file dialog window - `AT - Add Track` button.\n        - `MEDIA_FILES`'s listed file types used to select the correct files from the selected dictionary\n      and subdirectories - `AD - Add Directory` button.\n    - Currently listed extensions:\n        - Audio: *.aac *.dts *.flac *.m4a *.midi *.mp3 *.ogg *.wav\n        - Video: *.avi *.flv *.mkv *.mov *.mp4 *.mpeg *.mts *.webm *.wmv\n- To check if a file with unlisted extension is payable:\n    - Click `AT - Add Track` button\n    - In the pop-up window navigate to the file location\n    - At the bottom of the pop-up window change the `Files of type` to `All files (*.*)`\n    - Add the file to the playlist and try to play it\n\n## Workarounds\n### Dummy track\n- Issue: the first track has to be played from the start till the end before be able to switch to another track\n- Solution: dummy, empty track (\u003c 1 second) played at startup\n- More info: `src / av_player.py`\n- Side-effect:\n    - No visible side-effect\n    - Unlikely adding much to the launch time (Legion 5 laptop):\n        - Windows 11: 1.2 seconds\n        - Linux Mint 22: 0.4 seconds\n\n### Dummy playlist tab\n- Issue: if the last playlist tab is hidden, the whole playlist tab list is not reachable via the arrow buttons \n- Solution: The last, dummy, disabled playlist tab always visible\n    - More info: `src / playlists.py`\n    - Side-effect: disabled, not clickable, small pice is visible on the right side of the playlists bar\n\n### Information displayed as subtitle\n- Issue: the video scene composition not following the layout, frame size change\n    - Window \u003c- QFrame \u003c- Layout \u003c- QGraphicsView \u003c- QGraphicsScene \u003c- QGraphicsVideoItem\n- Solution: the information (track title, volume, ..) displayed as subtitle on the video screen\n    - Side-effect: When the video is not playing, the information is not displayed\n\n### Audio delay - LINUX only\n- Issue: video or audio paused + continue playing\n    - Video continue normally\n    - Audio is not playing for a while (2-10s)\n- Solution: saving the current player`s position at pause and apply it at the continue phase\n\n### Audio device change - LINUX only\n- Issue: Switching audio device on PC/laptop \u003e\u003e **freezes the app, no error message.\n  - ** src / av_player updated to avoid\n  - It is working without any issue with PyQt(6.9.0).\n- Solution: right-click on the video and select the preferred audio device or restart the app\n\n### Could not find solution yet\n- Issue: the video`s own subtitles are not displayed correctly, VLC player recommended for subbed movies\n\n\n## Requirements\n### Python 3 - used: 3.11.5\n- https://www.python.org/\n\n### Install dependencies\n``` pip install -r requirements.txt ```\n\n### Additional dependency for Linux\n``` sudo apt install libxcb-cursor-dev ```\n\n### FFmpeg [(link)](https://ffmpeg.org/)\n- `FFmpeg` used to generate thumbnail images from the video media\n- Without `FFmpeg`\n  - The `Thumbnail View button` is disabled\n  - The media player is still fully functioning \n- WINDOWS\n    - [Install FFmpeg on Windows 10/11](https://techtactician.com/how-to-install-ffmpeg-and-add-it-to-path-on-windows/)\n- LINUX\n    - Via `Software Manager`\n\n\n### OS\n- Tested on Windows 11, Linux Mint 22\n\n## Thank you all who worked on the modules used in this project!\n## Thank you all Winamp, VLC player and Total/Double Commander contributors!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk4karole%2Fqtea_media_player","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fk4karole%2Fqtea_media_player","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk4karole%2Fqtea_media_player/lists"}