{"id":17932853,"url":"https://github.com/dbatbold/beep","last_synced_at":"2025-08-20T17:26:33.843Z","repository":{"id":25188756,"uuid":"28612160","full_name":"dbatbold/beep","owner":"dbatbold","description":"Beep sound library and utility for alerting end of a command execution. Beep can also play MIDI or text music score.","archived":false,"fork":false,"pushed_at":"2023-03-22T02:28:21.000Z","size":522,"stargazers_count":58,"open_issues_count":2,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-19T02:59:01.698Z","etag":null,"topics":["beep","go","midi","music-sheet"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dbatbold.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}},"created_at":"2014-12-30T00:54:06.000Z","updated_at":"2024-10-27T09:20:43.000Z","dependencies_parsed_at":"2024-06-18T21:22:33.032Z","dependency_job_id":"5309318b-892f-4176-8e7d-35b7dffbe835","html_url":"https://github.com/dbatbold/beep","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbatbold%2Fbeep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbatbold%2Fbeep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbatbold%2Fbeep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbatbold%2Fbeep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dbatbold","download_url":"https://codeload.github.com/dbatbold/beep/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245222581,"owners_count":20580189,"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","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":["beep","go","midi","music-sheet"],"created_at":"2024-10-28T21:32:36.462Z","updated_at":"2025-03-24T06:31:29.730Z","avatar_url":"https://github.com/dbatbold.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"beep\n====\n\nBeep is a sound utility initially developed for alerting the end of a long running command execution.\nNow beep can also play a MIDI file/URL or text music score with natural voices. To play demo music, run:\u003cbr\u003e\n\n```\n$ go install github.com/dbatbold/beep/cmd/beep@latest\n$ ~/go/bin/beep           # play beep sound\n$ ~/go/bin/beep -vd       # download natural voice files\n$ ~/go/bin/beep -m demo1  # play demo music by Mozart\n$ ~/go/bin/beep -m demo2  # play Passacaglia - Handel Halvorsen\n```\n\n[Play demo #1 with piano voice\u0026nbsp; ▶](http://bmrust.com/dl/beep/demo-mozart-k33b-piano.mp3)\u003cbr\u003e\n[Play demo #2 with piano voice\u0026nbsp; ▶](http://bmrust.com/dl/beep/passacaglia-handel-halvorsen-piano.mp3)\u003cbr\u003e\n\nLibrary Usage\n=============\n\n```go\npackage main\n\nimport (\n    \"bufio\"\n    \"strings\"\n    \"log\"\n    \"github.com/dbatbold/beep\"\n)\n\nfunc main() {\n    music := beep.NewMusic(\"\") // output can be a file \"music.wav\"\n    volume := 100\n\n    if err := beep.OpenSoundDevice(\"default\"); err != nil {\n        log.Fatal(err)\n    }\n    if err := beep.InitSoundDevice(); err != nil {\n        log.Fatal(err)\n    }\n    beep.PrintSheet = true\n    defer beep.CloseSoundDevice()\n\n    musicScore := `\n        VP SA8 SR9\n        A9HRDE cc DScszs|DEc DQzDE[|cc DScszs|DEc DQz DE[|vv DSvcsc|DEvs ]v|cc DScszs|VN\n        A3HLDE [n z,    |cHRq HLz, |[n z,    |cHRq HLz,  |sl z,    |]m   pb|z, ]m    |\n        \n        A9HRDE cz [c|ss DSsz]z|DEs] ps|DSsz][ z][p|DEpDQ[ [|VN\n        A3HLDE [n ov|]m [n    |  pb ic|  n,   lHRq|HLnc DQ[|\n    `\n\n    reader := bufio.NewReader(strings.NewReader(musicScore))\n    go music.Play(reader, volume)\n    music.Wait()\n    beep.FlushSoundBuffer()\n}\n\n```\n\nBuilding from Source\n====================\n```\nOn Linux:\n $ apt-get install golang libasound2-dev  # for Debian and Ubuntu\n $ apk add alsa-lib-dev                   # for Alpine linux\n $ go build ./cmd/beep\n $ cp beep /usr/local/bin/  # as root\n\nOn Windows: Requires git (git-scm.com), MinGW and Go compiler (golang.org)\n Run Git Bash,\n $ export GOPATH=$PWD/beep\n $ go get -u -v -d github.com/dbatbold/beep/cmd/beep\n $ cd beep\n $ ./build.bat\n $ cp bin/beep.exe /c/Windows/System32\n```\n[![CI](https://github.com/dbatbold/beep/actions/workflows/ci.yml/badge.svg)](https://github.com/dbatbold/beep/actions/workflows/ci.yml)\n\nUsage\n=====\n\n```\nbeep [options]\n  -c=1: beep count\n  -d=\"default\": audio device, Linux example: hw:0,0\n  -f=523.25: frequency in Hertz (1-22050)\n  -h: print help\n  -l: beep per line from stdin\n  -m: play music from sheet file, reads stdin if no arguments given (see beep notation)\n  -p=0: print demo music sheet by number (1-2)\n  -t=250: beep time duration in millisecond (1-60000)\n  -v=100: volume (1-100)\n  -b: send bell to PC speaker\n  -q: quiet stdout while playing music\n  -n: print notes while playing music\n  -o=file: output music waveform to a WAV file. Use '-' for stdout\n  -w: start beep web server\n  -a ip:port: web server address (default 127.0.0.1:4444)\n  -vd [name ..]: download voice files, if no names given, downloads all voices\n  -mp=file: play a MIDI file\n  -mu=URL: play a MIDI file from URL\n  -mn=file: parses MIDI file and print notes\n  -play=notes: play notes from command argument\n  -battery: monitor battery and alert low charge level\n```\nBeep notation\n=============\n\nTo play music with beep, music score needs to be converted into text. Beep uses its own music notation called beep notation. All music octaves are divided into computer keyboard keys similar to piano key layout. All 88 piano notes can be played as following.\n```\n$ beep -play 'H0,l.HLq2w3er5t6y7ui9o0p[=]azsxcfvgbnjmk,l.HRq2w3er5t6y7ui9o0p[=]azsxcfvgbnjmk,l.H7q2w3er5t6y7ui'\n```\n[Play all piano notes \u0026nbsp; ▶](http://bmrust.com/dl/beep/piano-notes.mp3)\n\nUppercase \"H\" letter is a control key that changes the current octave. Lowercase letters are notes. Using all control keys shown below are used to convert musical notation.\n```\nPiano key map:\n  | | | | | | | | | | | | | | | | | | | | | | \n  |2|3| |5|6|7| |9|0| |=|a|s| |f|g| |j|k|l| |\n | | | | | | | | | | | | | | | | | | | | | | \n |q|w|e|r|t|y|u|i|o|p|[|]|z|x|c|v|b|n|m|,|.|\n\n q - middle C (261.6 hertz)\n\n Left and right hand keys are same. Uppercase \n letters are control keys. Lowercase letters\n are music notes. Space bar is current duration\n rest. Spaces after first space are ignored.\n Lines start with '#' are ignored.\n\nControl keys:\n\n Rest:\n RW     - whole rest\n RH     - half rest\n RQ     - quarter rest\n RE     - eighth rest\n RS     - sixteenth rest\n RT     - thirty-second rest\n RI     - sixty-fourth rest\n\n Durations:\n DW     - whole note\n DH     - half note\n DQ     - quarter note\n DE     - eighth note\n DS     - sixteenth note\n DT     - thirty-second note\n DI     - sixty-fourth note\n DD     - dotted note (adds half duration)\n\n Octave:\n H0     - octave 0 keys\n HL     - octave 1, 2, 3 (left hand keys)\n HR     - octave 4, 5, 6 (right hand keys)\n H7     - octave 7, 8 keys\n\n Tempo:\n T#     - where # is 0-9, default is 4 (1 unit speeds up/down by 4%)\n\n Sustain:\n SA#    - attack level, where # is 0-9, default is 8\n SD#    - decay level, 0-9, default 4\n SS#    - sustain level, 0-9, default 4\n SR#    - release level, 0-9, default 9\n\n Voice:\n VD     - Computer generated default voice\n VP     - Piano voice\n VV     - Violin voice (WIP)\n VN     - If a line ends with 'VN', the next line will be played \n          harmony with the line.\n\n Chord:\n C#     - Play next # notes as a chord, where # is 2-9. \n          For example C major chord is \"C3qet\"\n\n Amplitude:\n A#     - Changes current amplitude, where # is 1-9, default is 9\n\n Measures:\n |      - bar, ignored\n ' '    - space, ignored\n Tab    - tab, ignored\n\n Comments:\n #      - a line comment\n ##     - start or end of a block comment\n```\nDemo music #1\n=============\n```\n# Mozart K33b\nVP SA8 SR9\nA9HRDE cc DScszs|DEc DQzDE[|cc DScszs|DEc DQz DE[|vv DSvcsc|DEvs ]v|cc DScszs|VN\nA3HLDE [n z,    |cHRq HLz, |[n z,    |cHRq HLz,  |sl z,    |]m   pb|z, ]m    |\n\nA9HRDE cz [c|ss DSsz]z|DEs] ps|DSsz][ z][p|DEpDQ[ [|VN\nA3HLDE [n ov|]m [n    |  pb ic|  n,   lHRq|HLnc DQ[|\n\nA9HRDE cc DScszs|DEc DQzDE[|cc DScszs|DEc DQz DE[|vv DSvcsc|DEvs ]v|cc DScszs|VN\nA3HLDE [n z,    |cHRq HLz, |[n z,    |cHRq HLz,  |sl z,    |]m   pb|z, ]m    |\n\nA9HRDE cz [c|ss DSsz]z|DEs] ps|DSsz][ z][p|DEpDQ[ [|VN\nA3HLDE [n ov|]m [n    |  pb ic|  n,   lHRq|HLnc DQ[|\n\nA9HRDS DERE] DS][p[ |][p[ ][p[  |DE] DQp DEi|REc DScszs|cszs |cszs|DEcDQzDE[|REv DSvcsc|DEvs ]v|VN\nA3HLDE DEcHRq HLvHRw|HLbHRe HLvw|cHRq   HLic|[n  ]m    |z,   |]m  |zn   z,  |sl  [,    |z. DQp |\n\nA9HRDE REc DScszs|DEcz [c|REs DSsz]z|DEs] ps|DSsz][ z][p|DE[DSitDQr|VN\nA3HLDE z,  ]m    |[n   ov|]m  [n    |pb   ic|nz     sc  |DQn      [|\n\nA9HRDS DERE] DS][p[ |][p[ ][p[  |DE] DQp DEi|REc DScszs|cszs |cszs|DEcDQzDE[|REv DSvcsc|DEvs ]v|VN\nA3HLDE DEcHRq HLvHRw|HLbHRe HLvw|cHRq   HLic|[n  ]m    |z,   |]m  |zn   z,  |sl  [,    |z. DQp |\n\nA9HRDE REc DScszs|DEcz [c|REs DSsz]z|DEs] ps|DSsz][ z][p|DE[DSitDQrRQ|VN\nA3HLDE z,  ]m    |[n   ov|]m  [n    |pb   ic|nz     sc  |DQn      [RQ|\n```\n[Play with default voice\u0026nbsp; ▶](http://bmrust.com/dl/beep/demo-mozart-k33b.mp3)\u003cbr\u003e\n[Play with natural piano voice\u0026nbsp; ▶](http://bmrust.com/dl/beep/demo-mozart-k33b-piano.mp3)\u003cbr\u003e\n[View music score](http://imslp.org/images/1/15/TN-Mozart%2C_Wofgang_Amadeus-NMA_09_27_Band_02_I_01_KV_33b.jpg)\n\nDemo music #2\n=============\n```\n# Passacaglia - Handel Halvorsen\nVP T5 SA9 SD9 SS9 SR9\n# DQ - 130\nA6HRDE RERERERE RERERERE|RERERERE RERERERE|icxc   zc]c  |[cpc   ocic    |VN\nA4HLDE z,HReq   yqeq    |HLz,HReq yqeq    |HLz,HReq yqeq|HLov,n HRwHLn,n|\n# 5\nA6HRDE uxzx     ]x[x        |pxox ixux    |yz]z      [zpz        |oziz uzyz    |DQz DEa= DQDDa DEz|VN\nA4HLDE pmHRwHL. HRtHL.HRwHL.|icmb HRqHLbmb|[nmHRqHL, HRrHL,HRqHL,|ov,[ HRwHLn,n|pb  .k   HReHLk .k|\n# 10\nA6HRDW z          |DEcioi   pi[i|]izi   xici    |xuiu     oupu        |[u]u zuxu    |VN\nA4HLDE z,HReq yqeq|HLz,HReq yqeq|HLov,n HRwHLn,n|]mHRwHL. HRtHL.HRwHL.|icmb HRqHLbmb|\n# 15\nA6HRDE zyuy     iyoy        |py[y ]yzy    |DQz DEa= DQDDa DEz|DWz        |DEcH7qHR.H7q  HR,H7qHRmH7q|VN\nA4HLDE pbHRqHL, HRrHL,HRqHL,|ov,n HRwHLn,n|pb  .k   HReHLk .k|z,HReq yqeq|z,HReq yqeq               |\n# 20   8\nA6HRDE nH7qHRbH7q HRvH7qHRcH7q|HRx.,.   m.n.        |b.v. c.x.    |z,m,      n,b,        |v,c, x,z,    |VN\nA4HLDE ov,n       HRwHLn,n    |pmHRwHL. HRtHL.HRwHL.|icmb HRqHLbmb|[nmHRqHL, HRrHL,HRqHL,|ov,[ HRwHLn,n|\n# 25   8\nA6HRDQ , DEkj DQDDk DE,|DW,        |DEH7qHRcvc bcnc|mc,c   .cH7qHRc|.xcx     vxbx        |VN\nA4HLDE pb.k   HReHLk .k|z,HReq yqeq|HLz,HReq   yqeq|HLov,n HRwHLn,n|]mHRwHL. HRtHL.HRwHL.|\n# 30   8\nA6HRDE nxmx ,x.x    |.zxz     czvz        |bznz mz,z    |DQ, DEkj DQDDk DE,|DW,        |VN\nA4HLDE icmb HRqHLbmb|pbHRqHL, HRrHL,HRqHL,|ov,n HRwHLn,n|pb  .k   HReHLk .k|z,HReq yqeq|\n# 35\nA6HRDE iici   xizi|]i[i   pioi    |uuxu     zu]u        |[upu ouiu    |yyzy     ]y[y        |VN\nA4HLDE z,HReq yqeq|HLov,n HRwHLn,n|pbHRqHL, HRrHL,HRqHL,|icmb HRqHLbmb|pbHRqHL, HRrHL,HRqHL,|\n# 40                                               # 8va---------------------------\nA6HRDE pyoy iyuy    |DQy DE65 DQDD6 DEy|DWy        |DEcH7qHRx. z,]m|[npb   ovic    |VN\nA4HLDE ov,n HRwHLn,n|pb.k     HReHLk .k|z,HReq yqeq|HLz,HReq   yqeq|HLov,n HRwHLn,n|\n# 45   8\nA6HRDE x.z,   ]m[n|pbov   icux    |yzt]     r[ep        |woqi uHL.HRyHL,|HRDQy DE65 DQDD6 DEy|VN\nA4HLDE z,HReq yqeq|HLov,n HRwHLn,n|]mHRwHL. HRtHL.HRwHL.|ob,n ,n,n      |pb.k       HReHLk .k|\n# 50\nA6HRDW y          |DEicxc   zc]c|[cpc   ocic    |uxzx     ]x[x        |pxox ixux    |VN\nA4HLDE z,HReq yqeq|HLz,HReq yqeq|HLov,n HRwHLn,n|pmHRwHL. HRtHL.HRwHL.|icmb HRqHLbmb|\n# 55\nA6HRDE yz]z      [zpz        |oziz uzyz    |DQz DEa= DQDDa DEz|DWz        |DEcioi   pi[i|VN\nA4HLDE [nmHRqHL, HRrHL,HRqHL,|ov,[ HRwHLn,n|pb  .k   HReHLk .k|z,HReq yqeq|HLz,HReq yqeq|\n# 60\nA6HRDE ]izi xici    |xuiu     oupu        |[u]u zuxu    |zyuy     iyoy        |py[y ]yzy    |VN\nA4HLDE ov,n HRwHLn,n|]mHRwHL. HRtHL.HRwHL.|icmb HRqHLbmb|pbHRqHL, HRrHL,HRqHL,|ov,n HRwHLn,n|\n# 65\nA6HRDQ z DEa= DQDDa DEz  |DWz        |DEicxc zc]c|[cpc ocic|uxzx  ]x[x|VN\nA4HLDE pb  .k   HReHLk .k|z,HReq yqeq|HLDWC2,z   |C2vo     |C2m]      |\n# 70\nT3\nA6HRDE pxox ixux|yz]z [zpz|oziz uzyz|DQz DEa= DQDDa DEz|DWz |VN\nA4HLDW C2ci     |C2n[     |C2vo     |C2bp              |C2,z|\n```\n[Play with default voice\u0026nbsp; ▶](http://bmrust.com/dl/beep/passacaglia-handel-halvorsen.mp3)\u003cbr\u003e\n[Play with natural piano voice\u0026nbsp; ▶](http://bmrust.com/dl/beep/passacaglia-handel-halvorsen-piano.mp3)\u003cbr\u003e\n[View music score](https://azmusicfest.org/app/uploads/Passacaglia-Handel-Halvorsen-Pianistos-2.pdf)\n\nNatural Voices\n==============\n\nBeep uses computer generated voices if no voice files exist.\nA voice file is a ZIP file that contains sound samples of all notes that the\nmusic instrument can play. By downloading and placing voice files in specific locations can improve music sound quality.\n\nTo download voice files, run:\u003cbr\u003e\n```\n$ beep -vd  # downloads all voice files\n$ beep -vd piano # piano only\n$ beep -vd piano violin # piano and voice files\n```\nVoice files can also be downloaded manually. Move the files to location below after\ndownloading:\n\n**Voice files:**\u003cbr\u003e\n Piano voice: [piano.zip](http://bmrust.com/dl/beep/voices/piano.zip) (13MB)\u003cbr\u003e\n Violin voice: [violin.zip](http://bmrust.com/dl/beep/voices/piano.zip) (6.9MB)\u003cbr\u003e\n\n**Voice file location:**\u003cbr\u003e\n Windows: ```C:\\Users\\{username}\\_beep\\voices\\``` \u003cbr\u003e\n Linux: ```/home/{username}/.beep/voices/```\n\nWeb Interface\n=============\n\nPlaying a music sheet from command line can be slow to start, because voice\nfiles are loaded at startup for every time running beep.\nBeep has a built-in web server for playing and storing music sheets.\nThe web server loads voice files only once and uses them for all playback.\nTo start the web interface, run:\u003cbr\u003e\u003cbr\u003e\nLinux:\u003cbr\u003e\n```\n$ beep -w\n```\nWindows:\u003cbr\u003e\n```\nC:\\\u003ebeep -w\n```\nthen open your browser and navigate to ```http://localhost:4444```. If the web interface\nneeds to be accessible from other computers, run:\n```\n$ beep -w :4444\nor\n$ beep -w -a 0.0.0.0:4444  # for public access\n```\n\n**Screenshot:**\u003cbr\u003e\n![alt tag](http://bmrust.com/dl/beep/beep-web.png?1)\n\nUsage Examples\n==============\n```\n $ cp -vr directory target; beep\n $ ffmpeg -i video.mp4 -vn -acodec libmp3lame sound.mp3; beep -t 3000\n \n # use '\u0026' symbol instead of ';' on Windows\n C:\\\u003edir /s \\windows\\*.cpl \u0026 beep\n \n # alarm for download completion\n $ curl -O http://host.com/bigfile.tgz; beep -c 4 -f 1000\n \n # monitor battery and alarm low level\n $ beep -battery\n \n # beep for every text file found under home\n $ find ~ -name '*.txt' | beep -l\n \n # set an alarm for 1 hour from now\n $ sh -c 'sleep 3600; beep -t 300 -c 6' \u0026\n \n # play all piano notes\n $ echo \"DEH0,l.\\\n         HLq2w3er5t6y7ui9o0p[=]azsxcfvgbnjmk,l.\\\n         HRq2w3er5t6y7ui9o0p[=]azsxcfvgbnjmk,l.\\\n         H7q2w3er5t6y7ui\" | beep -m\n \n # play demo music by Mozart\n $ beep -m demo\n C:\\\u003ebeep -m demo\n\n # start beep web server and serve pages locally\n $ beep -w\n C:\\\u003ebeep -w  (or click Start then Run and type: beep -w)\n \n # start beep web server with open access\n $ beep -w :4444\n \n # dump music waveform to a WAV file\n $ beep -m -o music.wav demo \n \n # pipe to MP3 encoder\n $ beep -m -o - demo | lame - music.mp3\n \n # play misic sheet from files\n $ beep -m sheet.txt\n $ beep -m sheet1.txt sheet2.txt demo\n C:\\\u003ebeep -m sheet.txt\n\n # play music sheet from URL\n $ beep -url 'http://bmrust.com/dl/beep/k333-1.txt'\n $ beep -url 'http://bmrust.com/dl/beep/passacaglia-handel-halvorsen.txt'\n\n # generate 528Hz sine wave for 60 seconds (wine glass frequency)\n $ beep -f 528 -t 60000\n \n # middle C note\n $ beep -f 261.625565 -t 1500\n \n # play a MIDI file\n $ beep -mp music.mid\n \n # play a MIDI file from URL\n $ beep -mu 'https://www.guitarist.com/media/midi/classical/bach/jesu.mid'\n \n # print notes with keyboard from MIDI file\n $ beep -mn music.mid\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbatbold%2Fbeep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdbatbold%2Fbeep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbatbold%2Fbeep/lists"}