the web browser - GamerDuck123/copyparty GitHub Wiki

accessing a copyparty server using a web-browser

the main tabs in the ui

• [🔎] search by size, date, path/name, mp3-tags ...
• [🧯] unpost: undo/delete accidental uploads
• [🚀] and [🎈] are the uploaders
• [📂] mkdir: create directories
• [📝] new-md: create a new markdown document
• [📟] send-msg: either to server-log or into textfiles if --urlform save
• [🎺] audio-player config options
• [⚙️] general client config options

the browser has the following hotkeys (always qwerty)

• ? show hotkeys help
• B toggle breadcrumbs / navpane
• I/K prev/next folder
• M parent folder (or unexpand current)
• V toggle folders / textfiles in the navpane
• G toggle list / grid view -- same as 田 bottom-right
• T toggle thumbnails / icons
• ESC close various things
• ctrl-K delete selected files/folders
• ctrl-X cut selected files/folders
• ctrl-C copy selected files/folders to clipboard
• ctrl-V paste (move/copy)
• Y download selected files
• F2 rename selected file/folder
• when a file/folder is selected (in not-grid-view):
  • Up/Down move cursor
  • shift+Up/Down select and move cursor
  • ctrl+Up/Down move cursor and scroll viewport
  • Space toggle file selection
  • Ctrl-A toggle select all
• when a textfile is open:
  • I/K prev/next textfile
  • S toggle selection of open file
  • M close textfile
• when playing audio:
  • J/L prev/next song
  • U/O skip 10sec back/forward
  • 0..9 jump to 0%..90%
  • P play/pause (also starts playing the folder)
  • Y download file
• when viewing images / playing videos:
  • J/L, Left/Right prev/next file
  • Home/End first/last file
  • F toggle fullscreen
  • S toggle selection
  • R rotate clockwise (shift=ccw)
  • Y download file
  • Esc close viewer
  • videos:
    • U/O skip 10sec back/forward
    • 0..9 jump to 0%..90%
    • P/K/Space play/pause
    • M mute
    • C continue playing next video
    • V loop entire file
    • [ loop range (start)
    • ] loop range (end)
• when the navpane is open:
  • A/D adjust tree width
• in the grid view:
  • S toggle multiselect
  • shift+A/D zoom
• in the markdown editor:
  • ^s save
  • ^h header
  • ^k autoformat table
  • ^u jump to next unicode character
  • ^e toggle editor / preview
  • ^up, ^down jump paragraphs

switching between breadcrumbs or navpane

click the 🌲 or pressing the B hotkey to toggle between breadcrumbs path (default), or a navpane (tree-browser sidebar thing)

• [+] and [-] (or hotkeys A/D) adjust the size
• [🎯] jumps to the currently open folder
• [📃] toggles between showing folders and textfiles
• [📌] shows the name of all parent folders in a docked panel
• [a] toggles automatic widening as you go deeper
• [↵] toggles wordwrap
• [👀] show full name on hover (if wordwrap is off)

press g or 田 to toggle grid-view instead of the file listing and t toggles icons / thumbnails

• can be made default globally with --grid or per-volume with volflag grid
• enable by adding ?imgs to a link, or disable with ?imgs=0

it does static images with Pillow / pyvips / FFmpeg, and uses FFmpeg for video files, so you may want to --no-thumb or maybe just --no-vthumb depending on how dangerous your users are

• pyvips is 3x faster than Pillow, Pillow is 3x faster than FFmpeg
• disable thumbnails for specific volumes with volflag dthumb for all, or dvthumb / dathumb / dithumb for video/audio/images only
• for installing FFmpeg on windows, see optional dependencies

audio files are converted into spectrograms using FFmpeg unless you --no-athumb (and some FFmpeg builds may need --th-ff-swr)

images with the following names (see --th-covers) become the thumbnail of the folder they're in: folder.png, folder.jpg, cover.png, cover.jpg

• the order is significant, so if both cover.png and folder.jpg exist in a folder, it will pick the first matching --th-covers entry (folder.jpg)
• and, if you enable file indexing, it will also try those names as dotfiles (.folder.jpg and so), and then fallback on the first picture in the folder (if it has any pictures at all)

enabling multiselect lets you click files to select them, and then shift-click another file for range-select

• multiselect is mostly intended for phones/tablets, but the sel option in the [⚙️] settings tab is better suited for desktop use, allowing selection by CTRL-clicking and range-selection with SHIFT-click, all without affecting regular clicking
  • the sel option can be made default globally with --gsel or per-volume with volflag gsel

to show /icons/exe.png and /icons/elf.gif as the thumbnail for all .exe and .elf files respectively, do this: --ext-th=exe=/icons/exe.png --ext-th=elf=/icons/elf.gif

• optionally as separate volflags for each mapping; see config file example below
• the supported image formats are jpg, png, gif, webp, ico
  • be careful with svg; chrome will crash if you have too many unique svg files showing on the same page (the limit is 250 or so) -- showing the same handful of svg files thousands of times is ok however

config file example:

[global]
  no-thumb   # disable ALL thumbnails and audio transcoding
  no-vthumb  # only disable video thumbnails

[/music]
  /mnt/nas/music
  accs:
    r: *     # everyone can read
  flags:
    dthumb   # disable ALL thumbnails and audio transcoding
    dvthumb  # only disable video thumbnails
    ext-th:  exe=/ico/exe.png  # /ico/exe.png is the thumbnail of *.exe
    ext-th:  elf=/ico/elf.gif  # ...and /ico/elf.gif is used for *.elf
    th-covers:  folder.png,folder.jpg,cover.png,cover.jpg  # the default

download folders (or file selections) as zip or tar files

select which type of archive you want in the [⚙️] config tab:

• gzip default level is 3 (0=fast, 9=best), change with ?tar=gz:9
• xz default level is 1 (0=fast, 9=best), change with ?tar=xz:9
• bz2 default level is 2 (1=fast, 9=best), change with ?tar=bz2:9
• hidden files (dotfiles) are excluded unless account is allowed to list them
  • up2k.db and dir.txt is always excluded
• bsdtar supports streaming unzipping: curl foo?zip | bsdtar -xv
  • good, because copyparty's zip is faster than tar on small files
    • but ?tar is better for large files, especially if the total exceeds 4 GiB
• zip_crc will take longer to download since the server has to read each file twice
  • this is only to support MS-DOS PKZIP v2.04g (october 1993) and older
    • how are you accessing copyparty actually

you can also zip a selection of files or folders by clicking them in the browser, that brings up a selection editor and zip button in the bottom right

cool trick: download a folder by appending url-params ?tar&opus or ?tar&mp3 to transcode all audio files (except aac|m4a|mp3|ogg|opus|wma) to opus/mp3 before they're added to the archive

• super useful if you're 5 minutes away from takeoff and realize you don't have any music on your phone but your server only has flac files and downloading those will burn through all your data + there wouldn't be enough time anyways
• and url-params &j / &w produce jpeg/webm thumbnails/spectrograms instead of the original audio/video/images (&p for audio waveforms)
  • can also be used to pregenerate thumbnails; combine with --th-maxage=9999999 or --th-clean=0

drag files/folders into the web-browser to upload

dragdrop is the recommended way, but you may also:

• select some files (not folders) in your file explorer and press CTRL-V inside the browser window
• use the command-line uploader
• upload using curl, sharex, ishare, ...

when uploading files through dragdrop or CTRL-V, this initiates an upload using up2k; there are two browser-based uploaders available:

• [🎈] bup, the basic uploader, supports almost every browser since netscape 4.0
• [🚀] up2k, the good / fancy one

NB: you can undo/delete your own uploads with [🧯] unpost (and this is also where you abort unfinished uploads, but you have to refresh the page first)

up2k has several advantages:

• you can drop folders into the browser (files are added recursively)
• files are processed in chunks, and each chunk is checksummed
  • uploads autoresume if they are interrupted by network issues
  • uploads resume if you reboot your browser or pc, just upload the same files again
  • server detects any corruption; the client reuploads affected chunks
  • the client doesn't upload anything that already exists on the server
  • no filesize limit, even when a proxy limits the request size (for example Cloudflare)
• much higher speeds than ftp/scp/tarpipe on some internet connections (mainly american ones) thanks to parallel connections
• the last-modified timestamp of the file is preserved

it is perfectly safe to restart / upgrade copyparty while someone is uploading to it!
all known up2k clients will resume just fine 💪

see up2k for details on how it works, or watch a demo video

protip: you can avoid scaring away users with contrib/plugins/minimal-up2k.js which makes it look much simpler

protip: if you enable favicon in the [⚙️] settings tab (by typing something into the textbox), the icon in the browser tab will indicate upload progress -- also, the [🔔] and/or [🔊] switches enable visible and/or audible notifications on upload completion

the up2k UI is the epitome of polished intuitive experiences:

• "parallel uploads" specifies how many chunks to upload at the same time
• [🏃] analysis of other files should continue while one is uploading
• [🥔] shows a simpler UI for faster uploads from slow devices
• [🛡️] decides when to overwrite existing files on the server
  • 🛡️ = never (generate a new filename instead)
  • 🕒 = overwrite if the server-file is older
  • ♻️ = always overwrite if the files are different
• [🎲] generate random filenames during upload
• [🔎] switch between upload and file-search mode
  • ignore [🔎] if you add files by dragging them into the browser

and then theres the tabs below it,

• [ok] is the files which completed successfully
• [ng] is the ones that failed / got rejected (already exists, ...)
• [done] shows a combined list of [ok] and [ng], chronological order
• [busy] files which are currently hashing, pending-upload, or uploading
  • plus up to 3 entries each from [done] and [que] for context
• [que] is all the files that are still queued

note that since up2k has to read each file twice, [🎈] bup can theoretically be up to 2x faster in some extreme cases (files bigger than your ram, combined with an internet connection faster than the read-speed of your HDD, or if you're uploading from a cuo2duo)

if you are resuming a massive upload and want to skip hashing the files which already finished, you can enable turbo in the [⚙️] config tab, but please read the tooltip on that button

if the server is behind a proxy which imposes a request-size limit, you can configure up2k to sneak below the limit with server-option --u2sz (the default is 96 MiB to support Cloudflare)

if you want to replace existing files on the server with new uploads by default, run with --u2ow 2 (only works if users have the delete-permission, and can still be disabled with 🛡️ in the UI)

dropping files into the browser also lets you see if they exist on the server

when you drag/drop files into the browser, you will see two dropzones: Upload and Search

on a phone? toggle the [🔎] switch green before tapping the big yellow Search button to select your files

the files will be hashed on the client-side, and each hash is sent to the server, which checks if that file exists somewhere

files go into [ok] if they exist (and you get a link to where it is), otherwise they land in [ng]

• the main reason filesearch is combined with the uploader is cause the code was too spaghetti to separate it out somewhere else, this is no longer the case but now i've warmed up to the idea too much

undo/delete accidental uploads using the [🧯] tab in the UI

you can unpost even if you don't have regular move/delete access, however only for files uploaded within the past --unpost seconds (default 12 hours) and the server must be running with -e2d

config file example:

[global]
  e2d            # enable up2k database (remember uploads)
  unpost: 43200  # 12 hours (default)

uploads can be given a lifetime, after which they expire / self-destruct

the feature must be enabled per-volume with the lifetime upload rule which sets the upper limit for how long a file gets to stay on the server

clients can specify a shorter expiration time using the up2k ui -- the relevant options become visible upon navigating into a folder with lifetimes enabled -- or by using the life upload modifier

specifying a custom expiration time client-side will affect the timespan in which unposts are permitted, so keep an eye on the estimates in the up2k ui

download files while they're still uploading (demo video) -- it's almost like peer-to-peer

requires the file to be uploaded using up2k (which is the default drag-and-drop uploader), alternatively the command-line program

the control-panel shows the ETA for all incoming files , but only for files being uploaded into volumes where you have read-access

cut/paste, rename, and delete files/folders (if you have permission)

file selection: click somewhere on the line (not the link itself), then:

• space to toggle

• up/down to move

• shift-up/down to move-and-select

• ctrl-shift-up/down to also scroll

• shift-click another line for range-select

• cut: select some files and ctrl-x

• copy: select some files and ctrl-c

• paste: ctrl-v in another folder

• rename: F2

you can copy/move files across browser tabs (cut/copy in one tab, paste in another)

share a file or folder by creating a temporary link

when enabled in the server settings (--shr), click the bottom-right share button to share the folder you're currently in, or alternatively:

• select a folder first to share that folder instead
• select one or more files to share only those files

this feature was made with identity providers in mind -- configure your reverseproxy to skip the IdP's access-control for a given URL prefix and use that to safely share specific files/folders sans the usual auth checks

when creating a share, the creator can choose any of the following options:

• password-protection
• expire after a certain time; 0 or blank means infinite
• allow visitors to upload (if the user who creates the share has write-access)

semi-intentional limitations:

• cleanup of expired shares only works when global option e2d is set, and/or at least one volume on the server has volflag e2d
• only folders from the same volume are shared; if you are sharing a folder which contains other volumes, then the contents of those volumes will not be available
• if you change password hashing settings after creating a password-protected share, then that share will stop working
• related to IdP volumes being forgotten on shutdown, any shares pointing into a user's IdP volume will be unavailable until that user makes their first request after a restart
• no option to "delete after first access" because tricky
  • when linking something to discord (for example) it'll get accessed by their scraper and that would count as a hit
  • browsers wouldn't be able to resume a broken download unless the requester's IP gets allowlisted for X minutes (ref. tricky)

specify --shr /foobar to enable this feature; a toplevel virtual folder named foobar is then created, and that's where all the shares will be served from

• you can name it whatever, foobar is just an example
• if you're using config files, put shr: /foobar inside the [global] section instead

users can delete their own shares in the controlpanel, and a list of privileged users (--shr-adm) are allowed to see and/or delet any share on the server

after a share has expired, it remains visible in the controlpanel for --shr-rt minutes (default is 1 day), and the owner can revive it by extending the expiration time there

security note: using this feature does not mean that you can skip the accounts and volumes section -- you still need to restrict access to volumes that you do not intend to share with unauthenticated users! it is not sufficient to use rules in the reverseproxy to restrict access to just the /share folder.

select some files and press F2 to bring up the rename UI

quick explanation of the buttons,

• [✅ apply rename] confirms and begins renaming
• [❌ cancel] aborts and closes the rename window
• [↺ reset] reverts any filename changes back to the original name
• [decode] does a URL-decode on the filename, fixing stuff like & and %20
• [advanced] toggles advanced mode

advanced mode: rename files based on rules to decide the new names, based on the original name (regex), or based on the tags collected from the file (artist/title/...), or a mix of both

in advanced mode,

• [case] toggles case-sensitive regex
• regex is the regex pattern to apply to the original filename; any files which don't match will be skipped
• format is the new filename, taking values from regex capturing groups and/or from file tags
  • very loosely based on foobar2000 syntax
• presets lets you save rename rules for later

available functions:

• $lpad(text, length, pad_char)
• $rpad(text, length, pad_char)

so,

say you have a file named meganeko - Eclipse - 07 Sirius A.mp3 (absolutely fantastic album btw) and the tags are: Album:Eclipse, Artist:meganeko, Title:Sirius A, tn:7

you could use just regex to rename it:

• regex = (.*) - (.*) - ([0-9]{2}) (.*)
• format = (3). (1) - (4)
• output = 07. meganeko - Sirius A.mp3

or you could use just tags:

• format = $lpad((tn),2,0). (artist) - (title).(ext)
• output = 7. meganeko - Sirius A.mp3

or a mix of both:

• regex = - ([0-9]{2})
• format = (1). (artist) - (title).(ext)
• output = 07. meganeko - Sirius A.mp3

the metadata keys you can use in the format field are the ones in the file-browser table header (whatever is collected with -mte and -mtp)

monitor a folder with your RSS reader , optionally recursive

must be enabled per-volume with volflag rss or globally with --rss

the feed includes itunes metadata for use with podcast readers such as AntennaPod

a feed example: https://cd.ocv.me/a/d2/d22/?rss&fext=mp3

url parameters:

• pw=hunter2 for password auth
• recursive to also include subfolders
• title=foo changes the feed title (default: folder name)
• fext=mp3,opus only include mp3 and opus files (default: all)
• nf=30 only show the first 30 results (default: 250)
• sort=m sort by mtime (file last-modified), newest first (default)
  • u = upload-time; NOTE: non-uploaded files have upload-time 0
  • n = filename
  • a = filesize
  • uppercase = reverse-sort; M = oldest file first

list all recent uploads by clicking "show recent uploads" in the controlpanel

will show uploader IP and upload-time if the visitor has the admin permission

• global-option --ups-when makes upload-time visible to all users, and not just admins

• global-option --ups-who (volflag ups_who) specifies who gets access (0=nobody, 1=admins, 2=everyone), default=2

note that the 🧯 unpost feature is better suited for viewing your own recent uploads, as it includes the option to undo/delete them

config file example:

[global]
  ups-when    # everyone can see upload times
  ups-who: 1  # but only admins can see the list,
              # so ups-when doesn't take effect

plays almost every audio format there is (if the server has FFmpeg installed for on-demand transcoding)

the following audio formats are usually always playable, even without FFmpeg: aac|flac|m4a|mp3|ogg|opus|wav

some hilights:

• OS integration; control playback from your phone's lockscreen (windows // iOS // android)
• shows the audio waveform in the seekbar
• not perfectly gapless but can get really close (see settings + eq below); good enough to enjoy gapless albums as intended
• videos can be played as audio, without wasting bandwidth on the video

click the play link next to an audio file, or copy the link target to share it (optionally with a timestamp to start playing from, like that example does)

open the [🎺] media-player-settings tab to configure it,

• "switches":
  • [🔁] repeats one single song forever
  • [🔀] shuffles the files inside each folder
  • [preload] starts loading the next track when it's about to end, reduces the silence between songs
  • [full] does a full preload by downloading the entire next file; good for unreliable connections, bad for slow connections
  • [~s] toggles the seekbar waveform display
  • [/np] enables buttons to copy the now-playing info as an irc message
  • [📻] enables buttons to create an m3u playlist with the selected songs
  • [os-ctl] makes it possible to control audio playback from the lockscreen of your device (enables mediasession)
  • [seek] allows seeking with lockscreen controls (buggy on some devices)
  • [art] shows album art on the lockscreen
  • [🎯] keeps the playing song scrolled into view (good when using the player as a taskbar dock)
  • [⟎] shrinks the playback controls
• "buttons":
  • [uncache] may fix songs that won't play correctly due to bad files in browser cache
• "at end of folder":
  • [loop] keeps looping the folder
  • [next] plays into the next folder
• "transcode":
  • [flac] converts flac and wav files into opus (if supported by browser) or mp3
  • [aac] converts aac and m4a files into opus (if supported by browser) or mp3
  • [oth] converts all other known formats into opus (if supported by browser) or mp3
    • aac|ac3|aif|aiff|alac|alaw|amr|ape|au|dfpwm|dts|flac|gsm|it|m4a|mo3|mod|mp2|mp3|mpc|mptm|mt2|mulaw|ogg|okt|opus|ra|s3m|tak|tta|ulaw|wav|wma|wv|xm|xpk
• "transcode to":
  • [opus] produces an opus whenever transcoding is necessary (the best choice on Android and PCs)
  • [awo] is opus in a weba file, good for iPhones (iOS 17.5 and newer) but Apple is still fixing some state-confusion bugs as of iOS 18.2.1
  • [caf] is opus in a caf file, good for iPhones (iOS 11 through 17), technically unsupported by Apple but works for the most part
  • [mp3] -- the myth, the legend, the undying master of mediocre sound quality that definitely works everywhere
• "tint" reduces the contrast of the playback bar

create and play m3u8 playlists -- see example text and player

click a file with the extension m3u or m3u8 (for example mixtape.m3u or touhou.m3u8 ) and you get two choices: Play / Edit

playlists can include songs across folders anywhere on the server, but filekeys/dirkeys are NOT supported, so the listener must have read-access or get-access to the files

with a standalone mediaplayer or copyparty

you can use foobar2000, deadbeef, just about any standalone player should work -- but you might need to edit the filepaths in the playlist so they fit with the server-URLs

alternatively, you can create the playlist using copyparty itself:

• open the [🎺] media-player-settings tab and enable the [📻] create-playlist feature -- this adds two new buttons in the bottom-right tray, [📻add] and [📻copy] which appear when you listen to music, or when you select a few audiofiles

• click the 📻add button while a song is playing (or when you've selected some songs) and they'll be added to "the list" (you can't see it yet)

• at any time, click 📻copy to send the playlist to your clipboard

  • you can then continue adding more songs if you'd like
  • if you want to wipe the playlist and start from scratch, just refresh the page

• create a new textfile, name it something.m3u and paste the playlist there

and dynamic range compressor

can also boost the volume in general, or increase/decrease stereo width (like crossfeed just worse)

has the convenient side-effect of reducing the pause between songs, so gapless albums play better with the eq enabled (just make it flat)

not available on iPhones / iPads because AudioContext currently breaks background audio playback on iOS (15.7.8)

due to phone / app settings, android phones may randomly stop playing music when the power saver kicks in, especially at the end of an album -- you can fix it by disabling power saving in the app settings of the browser you use for music streaming (preferably a dedicated one)

with realtime streaming of logfiles and such (demo) , and terminal colors work too

click -txt- next to a textfile to open the viewer, which has the following toolbar buttons:

• ✏️ edit opens the textfile editor
• 📡 follow starts monitoring the file for changes, streaming new lines in realtime
  • similar to tail -f
  • link directly to a file with tailing enabled by adding &tail to the textviewer URL

and there are two editors

there is a built-in extension for inline clickable thumbnails;

• enable it by adding <!-- th --> somewhere in the doc
• add thumbnails with !th[l](your.jpg) where l means left-align (r = right-align)
• a single line with --- clears the float / inlining
• in the case of README.md being displayed below a file listing, thumbnails will open in the gallery viewer

other notes,

• the document preview has a max-width which is the same as an A4 paper when printed

dynamic docs with serverside variable expansion to replace stuff like {{self.ip}} with the client's IP, or {{srv.htime}} with the current time on the server

see ./srv/expand/ for usage and examples

• you can link a particular timestamp in an audio file by adding it to the URL, such as &20 / &20s / &1m20 / &t=1:20 after the .../#af-c8960dab

• enabling the audio equalizer can help make gapless albums fully gapless in some browsers (chrome), so consider leaving it on with all the values at zero

• get a plaintext file listing by adding ?ls=t to a URL, or a compact colored one with ?ls=v (for unix terminals)

• if you are using media hotkeys to switch songs and are getting tired of seeing the OSD popup which Windows doesn't let you disable, consider ./contrib/media-osd-bgone.ps1

• click the bottom-left π to open a javascript prompt for debugging

• files named .prologue.html / .epilogue.html will be rendered before/after directory listings unless --no-logues

• files named descript.ion / DESCRIPT.ION are parsed and displayed in the file listing, or as the epilogue if nonstandard

• files named README.md / readme.md will be rendered after directory listings unless --no-readme (but .epilogue.html takes precedence)

  • and PREADME.md / preadme.md is shown above directory listings unless --no-readme or .prologue.html

• README.md and *logue.html can contain placeholder values which are replaced server-side before embedding into directory listings; see --help-exp

search by size, date, path/name, mp3-tags, ...

when started with -e2dsa copyparty will scan/index all your files. This avoids duplicates on upload, and also makes the volumes searchable through the web-ui:

• make search queries by size/date/directory-path/filename, or...
• drag/drop a local file to see if the same contents exist somewhere on the server, see file-search

path/name queries are space-separated, AND'ed together, and words are negated with a - prefix, so for example:

• path: shibayan -bossa finds all files where one of the folders contain shibayan but filters out any results where bossa exists somewhere in the path
• name: demetori styx gives you good stuff

the raw field allows for more complex stuff such as ( tags like *nhato* or tags like *taishi* ) and ( not tags like *nhato* or not tags like *taishi* ) which finds all songs by either nhato or taishi, excluding collabs (terrible example, why would you do that)

for the above example to work, add the commandline argument -e2ts to also scan/index tags from music files, which brings us over to: