Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Assignment 04: Oral History

In the final segment of our class, we discuss the use of non-textual media in history, especially oral histories. This final, short project asks you to take an existing piece of oral history and build a small web page around it. We will use a very similar set of templates to those we used last assignment; but instead of dealing with Google Maps, we’ll use the Popcorn events framework for creating a simple multi-media history essay out of HTML. As with our last assignment, this is a little bit like using hand-carved wooden Emoji: obviously there are much more sophisticated ways to interact with video on the web; our aim is to use this simple tool as a way to think about several issues:

  • How do aural and visual media change the nature of historical narrative?
  • What are the challenges of building an historical narrative around an oral history, especially one that you did not conduct yourself?
  • How does technical infrastructure (like Popcorn and Google Docs) change the nature of historical narrative?

How This Project Works

This is a very small(single-page!) website organized around an audio element. Though it might be used as a part of a larger project, it can also stand on its own. It looks pretty good, but most of the heavy lifting is done by outside libraries:

  • jQuery is an important piece of web infrastructure, widely used in many projects.
  • Remarkable is a “markdown parser” – it allows us to write the body of the essay in markdown and render it directly as HTML. A really big win.
  • Bootstrap is the most popular “web framework” in the world. It’s a sophisticated CSS & Javascript system that gets a lot of work done out of the box, and saves a huge amount of time
  • Popcorn.js was a Mozilla project in the early days of HTML5. It has some neat features that I haven’t been able to find in any more recent project so we’re still using it here.
  • Tabletop.js makes it very easy to use Google Docs spreadsheets as a data source.

Using these libraries gets us one step closer to “real-world” web development, where HTML and CSS is just a small part of your development time.

Your project has just a few files:

  • index.html, which loads the frameworks described above, adds a little extra Javascript which you can change if you want (but don’t need to), and sets up a basic HTML framework to give structure to the page (which you’re welcome to change and probably will want to).
  • index.md, where you will actually write your assignment! You’ll do it in Markdown, introducing fragments of HTML as you go where you need them. The current content of that file has examples of most of the syntax you’ll want to use (though obviously you’ll have to write the content yourself). index.md will be loaded by remarkable and inserted into an otherwise empty div in index.html.
  • extra-styles.css, which adds some modest additional style information, which, again, you are likely to want to change
  • popcorn-data.js or popcorn-data-from-google.js, at your discretion (I recommend using the Google sheets method)
  • your audio file, which is not being stored in this repository because it’s not such good practice to have a big file like that in the repository if no one’s going to use it. You will have to add the file to the repository and make sure the <audio> <source> points to it.
  • I also include local copies of the popcorn and tabletop libraries. The local popcorn, in particular, contains some small updates to keep the plugins working.

You should edit your files in Atom and make sure you have the htnl-preview package installed (go to Settings -> Install and search for “html preview”. Remarkable will only be able to access the contents of index.md properly when index.html being served by a webserver – fortunately the html preview runs a tiny server for you inside your editor. But if you try to just double click on index.html and open it in Google Chrome, you’ll be disappointed.

Checking Your Work

As we move closer to a real-world task, we start to encounter more real-world problems. Remarkable needs to acquire the contents of index.md so that that file can be processed and fed to index.html. But for many good reasons, the browser does not allow JavaScript to access local files. So our project will only work inside a web server. This makes debugging your work much harder!

Fortunately, there are many solutions. One is to use the Preview HTML functionality in Atom. You can even open a DevTools window (right click in the preview pane) to look at your error messages. However, sometimes it’s easier to just work in the full browser environment. That’s why I’ve added a server to the npm dependencies of this repository. This allows you to see your work in a regular browser tab. Simply navigate to the repository root directory in a terminal, and run npm install one more time, to fetch the new dependencies. Now whenever you want to look at your work, you can just run:

npm run server

Then point your browser at localhost:8080 and all the assignments in this repository will be available for you to browse.

Tips and Tricks

  • use the javascript seek function I defined to queue the audio file to a specific timecode in the file. You can call it with <a href="javascript:seek(135)"></a> – just replace 135 with whatever time you want to seek to, in seconds. Unfortunaely you’ll have to write this in plain old HTML as remarkable has trouble parsing javascript links.
  • load a different Bootstrap theme by copying the CSS link from the Bootstrap CDN. Feel free to experiment


  • Choose a short, online oral history audio clip (approximately 3 minutes in length). I recommend StoryCorps as a source, though there are many oral history archives online that are equally suitable. You will need to locate the actual media element in the oral history – this may be somewhat hidden, but searching for mp3 or <audio> in the source code or via the browser developer tools should help.
  • Listen to it carefully. What historical themes are suggested by it? What kinds of annotations might heighten the impact at crucial moments, or fill in background information at other times?
  • Create a short “video” to accompany the audio clip; use a variety of Popcorn plugins to accomplish this. In general, for 180 seconds you will likely need at least 15 events for the the video to feel approximately “full”.
  • Write a short essay, approximately 800 words in length, addressing any of the historical issues raised by the audio clip. Refer specifically to quotations from the clip. You may want to provide links to specific timecodes from the audio, though integrating that with Popcorn playback is unfortunately a little tricky. As in your last assignment, use simple links for citations, though you should provide page numbers wherever possible).


Your essay should meet the ordinary criteria for an historical essay: it should be clearly written, providing adequate evidence, have minimal spelling and grammatical errors, etc. The relationship between topic and clip should not be artificial – the essay should clarify or enlarge the historical circumstances that are brought to life by the clip.

Your popcorn events should be keyed to the rhythms of the clip itself, appearing and disappearing along with the themes that they refer to or address. They should enhance the impact of the clip rather than distract from it, and provide additional historical background that might not be found in the essay or the clip.

If you change the styling, you should not create a terrible mess! Certainly I think the page could be prettier and I welcome your improvements.

Technical Help

As usual, I am pretty much available to answer your questions. I also urge you to read this post, which has a fair amount of technical detail and also gives links to further documentation. Documentation of the popcorn event plugins used to be available online, but all that’s left now is the sourcecode on Github.


As usual, I will mark your assignment on the basis of the state of the master branch at the submission deadline. If you finish your work in on time, there’s no need to make any special branches.

For late work or resubmission of non-passing assignments, please create a new branch for me to look over. Because this repository contains several assignments, please name your resubmission branch resubmit-oh-1. Subsequent branches should be called resubmit-oh-2, resubmit-oh-3, etc.