Skip to content

Instantly share code, notes, and snippets.

@kigster
Last active June 19, 2024 03:07
Show Gist options
  • Save kigster/7ce9e879883cf4899fa0de94a57dfaf0 to your computer and use it in GitHub Desktop.
Save kigster/7ce9e879883cf4899fa0de94a57dfaf0 to your computer and use it in GitHub Desktop.
This shell script walks you through the steps required to change the monitor underscan or overscan value on OS-X, when the Display Preferences are not providing the underscan/overscan slider for a given display. This process was documented by Ishan Sharma here: http://ishan.co/external-monitor-underscan and is a part of BashMatic library.
#!/usr/bin/env bash
#
# Script to change underscan/overscan value of a monitor on OS-X.
# © 2016-2019 Konstantin Gredeskoul, distributed under the MIT License.
#
#———————————————————————————————————————————————————————————————————————————————————————————
# EXCEPT AS REPRESENTED IN THIS AGREEMENT, ALL WORK PRODUCT BY DEVELOPER IS PROVIDED "AS IS".
# OTHER THAN AS PROVIDED IN THIS AGREEMENT, DEVELOPER MAKES NO OTHER WARRANTIES, EXPRESS OR
# IMPLIED, AND HEREBY DISCLAIMS ALL IMPLIED WARRANTIES, INCLUDING ANY WARRANTY OF
# MERCHANTABILITY AND WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE.
#———————————————————————————————————————————————————————————————————————————————————————————
#
# How to run this script?
# 1. Open Terminal application (/Applications/Utilities/Terminal.app)
#
# 2. Decide if you want to reduce (negative) or increase (positive) screen size.
# You should think of a number of percentage points to change it by, for example
# it could be -5 (for underscan) or 5 for overscan.
#
# 3. Set the following variable to this number by pasting the following, and changing the value:
#
# export SCAN_CHANGE_PERCENT=5 # overscan, change 5 to -5 for underscan
#
# 3. Copy and paste the following commands:
#
# curl -fsSL http://bit.ly/change-underscan-osx > ./change-underscan
# chmod 755 ./change-underscan
# ./change-underscan ${SCAN_CHANGE_PERCENT}
#
# 4. You can also run it as:
#
# ./change-underscan 5
#
# 5. Follow the prompts and perform actions asked by the script.
#
# 6. Enjoy being able to see Mac OSX top menu and your dock :)
curl -fsSL http://bit.ly/bashmatic-bootstrap | /usr/bin/env bash
if [[ -d ~/.bashmatic ]]; then
source ~/.bashmatic/init.sh
change-underscan "$1"
else
echo "The script $0 was installed correctly, however underlying library"
echo "was not. Please install it by running the following:"
echo
echo " cd ~/"
echo " curl -so bashmatic.zip https://codeload.github.com/kigster/bashmatic/zip/master"
echo " unzip bashmatic.zip && mv bashmatic-master ~/.bashmatic"
echo
echo "After that, re-run this script."
fi
@HashBah
Copy link

HashBah commented Jan 17, 2019

How do I open it properly? i downloaded it and tried to drag adn to open it manuaelly with terminal but nothing seem to work. it just gives says session finished.

@chestertc
Copy link

Managed to fix the problem in two iterations! Really awesome! Thank you so much!!

@z-sega
Copy link

z-sega commented Aug 30, 2019

(tears in my eyes)
This script is awesome.

@kigster
Copy link
Author

kigster commented Sep 4, 2019

How do I open it properly? i downloaded it and tried to drag adn to open it manuaelly with terminal but nothing seem to work. it just gives says session finished.

How to Run This Script

  1. Open Terminal application
  2. Paste the following code, setting SCAN_PERCENT to the percentage desired. Less than 100 is underscan, more than 100 is overscan.
SCAN_PERCENT=100
curl -fsSL http://bit.ly/fix-underscan > /tmp/fmu; bash /tmp/fmu ${SCAN_PERCENT}

@kigster
Copy link
Author

kigster commented Sep 4, 2019

(tears in my eyes)
This script is awesome.

❤️

@kigster
Copy link
Author

kigster commented Sep 18, 2019

Please note — the script now lives as a part of bashmatic library and therefore installs it into ~/.bashmatic.

@ianvoyager
Copy link

Hi kirsten, I have attempted to use your script many times however I simply cannot get it to work on my Mac Mini running 10.14.6 in regards to setting / resetting the overscan and under scan issues when connected to my TV via HDMI cable.

I have taken some screen shots of the errors or screens I get in terminal; here is the link.

Thanks in advance!

@kigster
Copy link
Author

kigster commented Sep 25, 2019

Yes, I can see the error thanks for posting images.

In the second screen shot you have ${10} as the last argument. Change that to just 10 and it should work.

I apologize as I’m working on bashmatic framework now and may have introduced breaking bugs, so email your screen shots to kigster AT gmail.com.

@ryanwwest
Copy link

This is awesome! However it inevitably leads to a scaled image, causing pixel blur since the resolution is no longer 1:1 with the pixel count. Is there a way in MacOS to instead change the resolution displayed on the monitor as this person did on Windows so you still use pixels 1:1, eliminating blur?

@itsazzad
Copy link

itsazzad commented Jul 2, 2020

How do I open it properly? i downloaded it and tried to drag adn to open it manuaelly with terminal but nothing seem to work. it just gives says session finished.

How to Run This Script

  1. Open Terminal application
  2. Paste the following code, setting SCAN_PERCENT to the percentage desired. Less than 100 is underscan, more than 100 is overscan.
SCAN_PERCENT=100
curl -fsSL http://bit.ly/fix-underscan > /tmp/fmu; bash /tmp/fmu ${SCAN_PERCENT}

/tmp/fmu: line 23: ~/.bashmatic/lib/Loader.bash: No such file or directory
/tmp/fmu: line 25: change-underscan: command not found

@yougotwill
Copy link

If this script isn't working for you I have found a working alternative for me. I hope this helps someone else :) https://github.com/univ-of-utah-marriott-library-apple/display_manager#underscan

@msropp
Copy link

msropp commented Sep 24, 2020

This works like a charm!!!

@kigster
Copy link
Author

kigster commented Sep 24, 2020

Glad someone is able to follow the instructions!!! LOL ♥️

@msropp
Copy link

msropp commented Sep 24, 2020

I was dealing with a monitor that is too big for my ergonomic comfort. I've had the right side and bottom taped off for months and had to move my dock to the left (shudder). I still had problems with not being able to see notifications in the notification center (upper right) due to the paper blocking that portion, as well as part of the menu bar. Now, I'm all good! :)

@ianvoyager
Copy link

Hello! I was the original question asker and I’m afraid I don’t really know how to implement these code based actions... 😅 ...Is anyone able to help me out? My understanding is I could create an icon on my desktop that I can double click and this will adjust the Overscan back to what it should be in system preferences...?

@kigster
Copy link
Author

kigster commented Sep 25, 2020

@ianvoyager Dear Ian, Mac OS-X is — behind the scenes — a UNIX-like system. You need to use Spotlight (⌘-Space) and search for "Terminal". Run the Terminal Application, and you will see a window with a prompt. You can type commands into the prompt, and the OS will execute them for you. You can read more about using Terminal and UNIX commands here: https://macpaw.com/how-to/use-terminal-on-mac

Once you have Terminal open, you can switch back to Chrome and copy the following commands:

curl -fsSL http://bit.ly/change-underscan-osx > ./change-underscan
bash ./change-underscan 5

(Make sure to press ENTER after the last command, in case it doesn't get run automatically.

You should replace "5" above with the value representing a percentage of the screen you want to resize by. Try starting with "5", if it goes the wrong direction, try again with "-5". And so on.

Hope this helps.

@billdlv
Copy link

billdlv commented Oct 14, 2020

I ran the script but I am getting Unable to find the display scan value to change error. I tried connecting a second display and still get the same error. I need to increase the screen size a bit so I used 5. I'm running 10.15.7. I also notice that the pscan key does not appear in the file.

@kigster
Copy link
Author

kigster commented Oct 14, 2020

@billdlv it’s possible OSX changed how they do this recently.

Having said that, the most important thing is to follow the riot instructions exactly. You need to unplug the monitor when it says so, and plug it back in when asked. Don’t skip any step! HTH

@robjr3
Copy link

robjr3 commented Oct 14, 2020

Hi, I've had the same problem with overscanning whenever I restart. The only solution I found was reseting the whole computer. I ran the scipt as described but when a window pops up for downloading it says it can't find the software. I have a macbook pro mid 2012 running catalina 10.15.7. what could possibly be wrong? thanks in advance.

@billdlv
Copy link

billdlv commented Oct 15, 2020

@billdlv it’s possible OSX changed how they do this recently.

Having said that, the most important thing is to follow the riot instructions exactly. You need to unplug the monitor when it says so, and plug it back in when asked. Don’t skip any step! HTH

I think it's changed, I tried another python based script univ-of-utah-marriott-library-apple/display_manager It also complains about not being able to find the parameter in the file.

@baebrum
Copy link

baebrum commented Nov 28, 2020

This script needs more coverage. Solved my problem in less than 10 minutes.

@shaizaa
Copy link

shaizaa commented Dec 3, 2020

@kigster - Is there a way to use this script for the built in display? My laptop fell and the display cracked slightly. I am not able to use about an inch of space on the right side of my monitor and would love to be able to use a modified version of this script to edit the built in display size.

@beegeesquare
Copy link

I'm trying to run the script and it is getting stuck, not matter how long I wait it is not proceeding any further. Can you provide some insight as to what could be the problem?

./change-underscan 5
✓   WARNING: This script is now deprecated and will be removed eventually.
✓            Please use the following to install Bashmatic moving forward:
✓            bash -c "$(curl -fsSL https://bashmatic.re1.re); bashmatic-install -v"
Already on 'master'

  « SUCCESS »    ✔  Your BashMatic has been successfully installed.

^C
ruby:1:in initialize: Interrupt

@fdominguezclaro
Copy link

Thank you @kigster! Worked perfectly on MacOS 11.5.1

@pedro-espinosa
Copy link

I have the exact same issue as @itsazzad

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment