Skip to content

Publishing

Jump to bottom
Kalinda Pride edited this page Apr 25, 2021 · 33 revisions

There are many ways to publish your LingView website to the internet. You can use GitHub's "Pages" feature, run your own server, share your LingView directory, use a cloud provider like Azure or AWS, or your institution may have a server that you can use.

Which option is best for me?

In most cases, we recommend GitHub Pages, because it's free, reasonably beginner-friendly, and can be set up quickly. See the next section for instructions. If your LingView site has files larger than 1 MB, such as videos or WAV files that are more than a few seconds long, you will need to host those files separately on YouTube, your own file server, or your institution's servers. If you need a file server and can pay for one, Linode Object Storage is a decent $5/month option. Everything you publish on GitHub Pages is available to the public, so you shouldn't use it if your LingView site contains confidential information.

To share your LingView website with specific people, you can email them a zipped folder or share your LingView directory using a service like Dropbox. First, check that LingView is working correctly on your computer by opening your copy of the index.html file. Then send your entire LingView directory to the recipient. (Or, if you want to send them a smaller directory and you don't need them to be able to change and rebuild their copy, you can instead run npm run bundle and send your bundle directory to the recipient.) The recipient can download your LingView directory to their computer, unzip it (if it was zipped), and then open the index.html file to view your LingView website. Unlike the other methods described here, the recipient won't see any changes you make to your LingView site unless they download an updated copy of your LingView directory.

If you can pay for publishing, and if GitHub Pages doesn't meet your needs, then consider Amazon Web Services, Microsoft Azure, or another cloud service provider. These services give you almost as much control as running your own server, they require somewhat less technical expertise, and they're designed to help you avoid common security mistakes. Expect to pay $5-$10/month for a basic server, or up to $100/month if you have many hours of video. Of course, your LingView website will become unavailable if you stop paying your subscription.

Most large institutions (universities, etc.) have their own servers, with technical staff who configure the servers and keep them running. If your institution allows it, you can publish your LingView website for free using one of your institution's servers, and your institution's technical staff may be available to guide you. If your project involves confidential information, your institution's technical staff can probably help you set up access controls to make it available to your research team without making it available to the public. For security reasons, most institutions won't give you full control of the server, so you'll have to rely on the technical staff to perform certain tasks for you, such as installing software and changing access permissions for files. In our experience, this can unfortunately result in long delays with setting up and updating the LingView site, especially if you want to make changes or customizations to the LingView software.

Using GitHub Pages

Here's how to publish your LingView website on GitHub Pages. If you have any files larger than 1 MB, see the end of this section for special instructions.

  1. Create your own LingView repository on GitHub. You can do this by clicking the "Fork" button in the top right corner of the BrownCLPS/LingView repository.
  2. In your new LingView repository, go to the "Settings" tab, then click "Pages" in the left sidebar. Under "Source", select the "gh-pages" branch, then click "Save".
  3. After a minute, you'll see a green banner in the "Pages" settings that says: "Your site is published at https://yourgithubusername.github.io/LingView/". Click that link to view your LingView website! But we're not done yet...
  4. In your LingView respository, go to the "Actions" tab, then click the green button to enable workflows.
  5. Optional: Consider cloning (downloading) your LingView repository to your computer, and drafting all your changes there. See below. If you skip this now, you can still decide to do it later.
  6. Make LingView your own! Add your own ELAN, FLEx, audio, and/or video files to replace the sample files in the data directory. You might also want to: add descriptive metadata for your ELAN and FLEx files; add content to the About and Glossary pages, or else remove these pages; change the website title and color scheme; or change which languages your website's visitors can use to navigate the page. Any changes you make to the master branch in your repository will show up on your website after a minute or so.

Local workflow

Consider cloning (downloading) your LingView repository to your computer, and drafting your changes there. This is less user-friendly than making all your changes directly on GitHub, but it will let you review your changes before publishing them. It also lets you use Git version control more fully, if you're into that.

Start by going to the "Code" tab in your LingView repository, then click the green "Code" button and choose "Open with GitHub Desktop". (If you don't want to install GitHub Desktop, you can use GitHub CLI instead, but I find the Desktop software is friendlier and easier to use.) When prompted, select "for my own purposes". Then follow the old Workflow instructions, starting from where it says "Download Node.js and NPM Packages".

When you're happy with your local changes and you want to publish them, commit and push your changes to the master branch of your LingView repository. After a minute or so, your LingView website will show your changes.

Large Files

If you have files larger than 1 MB, GitHub won't let you add them directly. GitHub suggests its Large File Storage tool when you try to upload large files, but unfortunately that tool doesn't work with GitHub Pages. You need to either reduce the size of your files, put your large files on YouTube, or store them on a file server.

Storing LingView videos on YouTube

If all of your large files are videos, we recommend hosting them on YouTube. To do this, upload the video to YouTube and then create a file with .youtube extension inside the media_files folder. This .youtube file should contain only 1 line that is the URL to this YouTube video. Ideally, the URL is in the format http:// or https://www.youtube.com/watch?v=<YouTube video ID>. LingView will use the provided URL and display a YouTube video frame on the corresponding ELAN or FLEx document's page. The YouTube video will be synced with the timestamps of the text on the document's page, just like videos hosted in other ways.

Using a file server

If YouTube doesn't meet your needs, we recommend hosting your large files on your institution's servers, if possible. A paid, cloud-based file server such as Amazon S3, Linode Object Storage, or Digital Ocean Spaces would also work well (typical cost is $5-$10/month). Unfortunately, Google Drive has overall and per-file rate limits that make it unsuitable for LingView websites.

  1. Put the media files on your server. Make sure each file has its own URL that you can use to view it over the internet.
  2. Tell LingView to look for remote media by setting an environment variable named MISSING_MEDIA to link (in most cases) or ignore (if you've configured your remote file storage to act as part of your computer's file system). Or, you can avoid setting the environment variable, and always rebuild using npm run quick-build-online (in most cases) or npm run quick-build-offline (if you've configured your remote file storage to act as part of your computer's file system).
  3. Tell LingView where to find your media by saving your file server URL as an environment variable named REMOTE_MEDIA_PATH. If you use GitHub Actions to build your LingView site, make sure to save this environment variable on GitHub, not only your local machine.
  4. When LingView looks for media files, if it can't find a matching audio or video file in data/media_files/, it looks for files with a matching name in your remote media path.

Reducing File Size

You can reduce the size of your audio and video files by changing their file format, decreasing their quality, and/or using shorter-duration files.

We recommend converting your audio files to .mp3, because it can make them much smaller while preserving good sound quality. However, note that phonetics software like Praat works only with .wav files, not with .mp3. So, if your audience wants to do their own phonetic analysis of your audio files, consider leaving your files in .wav format.

Quality: .wav files are usually recorded at "CD quality," which gives good detail and fidelity, even for music with a large range of intensities and frequencies. For speech, which involves a smaller range of frequencies, "CD quality" provides no noticeable benefit over "good quality." "Low quality" recordings of speech are noticeably worse, but still good enough for many linguistic applications.

Format Quality Size per Minute
.wav CD quality (44.1 kHz sample rate, 16-bit, stereo) 10 MB
.wav good quality for speech (22.05 kHz sample rate, 16-bit, mono) 2.5 MB
.wav low quality for speech (12 kHz sample rate, 8-bit, mono) 700 kB
.mp3 CD quality (160 kBps) 1.2 MB
.mp3 good quality for speech (128 kBps) 960 kB
.mp3 low quality for speech (96 kBps) 720 kB
.mp4 720p video, encoded with H.264 in ffmpeg or Handbrake 150 MB
.mp4 240p video, encoded with H.264 in ffmpeg or Handbrake 24 MB
.mp4 minimum quality talking head video (may require an encoding that's not available to the public) 960 kB

Sources for table:

If necessary, you can further reduce file size by splitting your FLEx or ELAN file into shorter clips, each with its own audio and/or video. You can do this manually (which might be quite cumbersome!), or you may be able to use a clip media script. LingView treats each FLEx and ELAN file as a completely separate document, so there's no built-in support for viewing the clips one after another. To increase the ease of viewing your LingView site, consider updating each clip's description to link to the previous and next clips.

Clone this wiki locally